Dependency and Artifact Versioning

What it is

A version is a promise. A dependency version tells a build exactly which code it gets. An artifact version tells a deployment exactly which build it is installing. A versioning strategy is the set of rules for how numbers are chosen, how consumers declare what they accept, and how a pipeline stamps its output.

Done well, any running system can be traced to one build, and rebuilding gives the same result. Done badly, a build that passed on Monday breaks on Tuesday because a dependency moved.

How it works

Semantic versioning (SemVer)

SemVer uses MAJOR.MINOR.PATCH, for example 2.4.1.

A prerelease label follows a hyphen (2.5.0-beta.1) and sorts before the final release. Build metadata follows a plus sign (2.5.0+20261009) and is ignored when comparing versions.

Calendar versioning (CalVer)

CalVer uses the release date, such as 2026.10 or 2026.10.3 (year, month, then a counter). It tells users how fresh a release is rather than how risky the change is.

Declaring dependency versions

In npm, ^1.4.2 allows new minor and patch versions (below 2.0.0), and ~1.4.2 allows new patch versions only. Floating versions risk surprises, so combine them with lock files: package-lock.json for npm and packages.lock.json for NuGet (with locked mode restore). A lock file records the exact resolved versions, and the pipeline installs from it (npm ci) so builds are repeatable.

Automate updates with Dependabot (or similar) so pinned versions do not rot: it opens pull requests that bump versions, and your tests decide whether to accept them. Use feed views and upstream settings to control which versions teams can pick up at all.

Versioning pipeline artifacts

A pipeline stamps every run with a build number and the artifact should carry it.

name: 1.4.$(Rev:r)   # run name, for example 1.4.7

steps:
- script: echo "Building $(Build.BuildNumber)"
- script: dotnet pack -p:PackageVersion=$(Build.BuildNumber)

For container images, tag with something unique and immutable such as the build ID or commit SHA. The latest tag moves, so deployments should not rely on it.

Rules for artifacts

• Immutable: once published, a version never changes. A fix is a new version.
• Build once, deploy many: one artifact moves through test, staging and production, rather than rebuilding per environment.
• Traceable: the version links to the commit, the run and the work items.
• Promotable: use feed views or release stages to promote the same artifact.

A worked scenario

A team publishes a shared library as a NuGet package and an app that uses it. The library uses SemVer and is built with GitVersion so the number follows the commit history. The app pins the library with a lock file and receives upgrade pull requests from Dependabot. The app pipeline is named 2026.10.$(Rev:r), stamps that on its container image along with the commit SHA, and deploys the identical image through test and production.