Dependency versioning strategy
Design a dependency versioning strategy
SemVer
For a stable public API at version 1.0.0 or later, MAJOR.MINOR.PATCH communicates compatibility:
| Increment | Meaning |
|---|---|
| MAJOR | Breaking change. Consumers must act. |
| MINOR | Backward-compatible functionality added. |
| PATCH | Backward-compatible fix. |
Major-zero versions (0.y.z) are initial development: anything may change and the public API should not be treated as stable.
Pre-release identifiers (1.4.0-beta.2) have lower precedence than the normal release they precede. Azure Artifacts view membership is a separate quality control: @prerelease is a suggested view, and packages enter a view through promotion rather than through SemVer ordering.
The value of SemVer is that a consumer can express intent — "any compatible update" — and have the range mean something. That only holds if publishers honour it; a MAJOR change shipped as a PATCH is worse than no scheme, because it defeats a guarantee consumers relied on.
CalVer
CalVer uses release-calendar tokens such as YYYY.0M.0D or YY.0M.MICRO. Projects choose the token combination that fits their cadence.
Choose CalVer when the project is time-sensitive or external events drive releases, such as distributions or frequently refreshed datasets. A CalVer project can still document separate compatibility rules; the date-based identifier communicates the release calendar.
Pinning
In an npm application, an exact package.json specification fixes a direct dependency but does not lock its transitive tree. A compatible manifest range can express update intent, while a committed package-lock.json records the exact resolved tree for reproducible installs. Deliberately refreshing and reviewing that lockfile makes dependency updates explicit.
Primary sources
- https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/az-400
- https://learn.microsoft.com/en-us/training/modules/implement-versioning-strategy/6-explore-best-practices-for-versioning
- https://semver.org/spec/v2.0.0.html
- https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/
- https://docs.npmjs.com/cli/v11/configuring-npm/package-json/
- https://docs.npmjs.com/cli/v11/commands/npm-install/
- https://calver.org/overview.html
- https://learn.microsoft.com/en-us/azure/devops/artifacts/concepts/views
- https://learn.microsoft.com/en-us/azure/devops/artifacts/feeds/views