Skip to main content

Dependency Management

Everything related to managing dependencies

Semver​

Availity creates open source projects that follow Semantic Versioning for dependency management. SemVer is a 3-component system in the format of x.y.z where:

  • x stands for a major version:
    • Breaking Change and NOT backwards compatible
    • Potential new features
    • Potential bug fixes
  • y stands for a minor version:
    • New Feature
    • Backwards compatible
  • z stands for a patch
    • Bug fix
    • Backwards compatible

For example, one of the libraries created and maintained by Availity is availity-workflow. This library is used by developers to create web applications using React. There have been many releases for availity-workflow and they follow semantic versioning.

The 1.x.x versions are fully compatible with each other. For example, if a project is using v1.0.0, a developer can be confident that upgrading to v1.0.1 or v1.1.0 it will not break their application.

When Availity identifies a need to make a breaking change, the major version number in the semantically versioned scheme is changed so that developers can understand how difficult it would be to upgrade. Upgrading is VOLUNTARY. It is up to the developer teams to determine if upgrading is necessary for their project(s). When availity-workflow@2.0.0 was released, Availity deemed the breaking changes necessary to push the platform forward. The breaking changes were documented in the changelog along with an upgrade path for older applications.

Availity released availity-workflow@3.0.0 to modernize the stack even further by leveraging Node 8 and dropping support for Node 6. Availity tries to keep its Node.js stack modern by matching the release schedule of the current active LTS (Long-Term Support) Node.js version. Once again, the changelog was documented so that developers can determine the difficulty factor when upgrading.

Changelog​

All Availity open-source projects maintain a changelog. Each project maintains it's own changelog. The changelog can be found in CHANGELOG.md for each package within a project.

Changelog.md Examples​

Tools​

It is up to the development team to decide if they want or need to upgrade any library in their stack. There are some tools available that help teams know if new releases of components have been published for use:

npm outdated​

❯ npm outdated --depth=0
Package                                 Current            Wanted        Latest  Location
awesome-bootstrap-checkbox                0.3.7             0.3.7         1.0.0  availity-toolkit > availity-uikit
bootstrap                                 3.3.7             3.3.7         4.0.0  availity-toolkit > availity-uikit

yarn upgrade-interactive --latest​

❯ yarn upgrade-interactive --latest
yarn upgrade-interactive v1.22.19
info Color legend :
 "<red>"    : Major Update backward-incompatible updates
 "<yellow>" : Minor Update backward-compatible features
 "<green>"  : Patch Update backward-compatible bug fixes
? Choose which packages to update. (Press <space> to select, <a> to toggle all, <i> to invert selection)
 dependencies
   name                    range   from             to            url
❯◯ @availity/favorites     latest  3.4.3         ❯  5.0.1         https://availity.github.io/availity-react/components/favorites/index
 ◯ @availity/spaces        latest  6.6.1         ❯  8.0.1         https://availity.github.io/availity-react/components/spaces/index

FAQ​

What happens when teams upgrade a library and the project/build breaks?​

  • Check the library changelog for BREAKING CHANGE announcements or recent fixes
  • Check the offending library issue board and see if tickets have been opened or closed similar to the issue being experienced.
  • If the problem can't be resolved, feel free to open an issue so that the Availity team can fix or provide feedback.
  • Rollback to previous library version if necessary

Why did minor or patch upgrade break my build/app?​

Availity strives to follow SemVer on every release but mistakes do happen and we try to quickly correct the issue. For example, availity-workflow@2.7.0 broke users on Node 6. The issue was identified availity-workflow/issues/135 and fixed in subsequent release availity-workflow@2.7.1

Credits​

Portions adopted from Semantic Versioning: Why You Should Be Using it