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

Dependency versioning strategy

Design a dependency versioning strategy

SemVer

CalVer

Pinning