Artifact Versioning Strategy

Introduction

Artifact versioning connects source changes with deployed binaries. A consistent strategy allows traceability, predictable rollbacks, and compatibility guarantees.

Semantic Versioning with Build Metadata

Use semantic versioning for public API compatibility and add build metadata for traceability:

• MAJOR.MINOR.PATCH for API changes.
• +build metadata for commit SHA or build number.

Version Sources

Prefer a single source of truth for the version:

• VERSION file in the repo.
• Git tags signed by release automation.
• Release pipeline that updates artifacts only during a release workflow.

Example: .NET Package Version

A .NET project can wire versioning directly into the project file.

<PropertyGroup>
  <Version>2.3.0</Version>
  <AssemblyVersion>2.3.0.0</AssemblyVersion>
  <FileVersion>2.3.0.0</FileVersion>
</PropertyGroup>

Compatibility Guarantees

For internal microservices, semantic versioning still matters for shared libraries and APIs. Enforce compatibility checks with contract tests and OpenAPI diff tooling.

Release Promotion

Once a version is cut, reuse that artifact across environments. Avoid re-tagging or rebuilding because it breaks traceability.

Summary

A strong artifact versioning strategy uses semantic versioning, immutable artifacts, and a single version source of truth. This ensures every deployment is traceable and reversible.