Accurate versioning is crucial for:

  • Ensuring compatibility and traceability of new features in the application and API.
  • Documenting functionality with reference to the specific version in which capabilities appeared.
  • Designating the current status of software product readiness (pre-release, alpha, beta).
  • Planning new functionality (roadmap).

Version Number

A version typically consists of several numbers separated by dots. The most common format is X.Y.Z (Major.Minor.Patch).

Rules:

  • Major: Incremented for incompatible API changes.
  • Minor: Incremented for adding functionality in a backward-compatible manner.
  • Patch: Incremented for backward-compatible bug fixes.

Semantic Versioning

It is recommended to follow the rules of Semantic Versioning (SemVer) when numbering versions.

Semantic Versioning is a widely adopted version scheme that uses a three-part version number (Major.Minor.Patch), an optional pre-release tag, and an optional build meta tag.

While SemVer allows a zero major version (0.y.z) for initial development, this can lead to inconsistency. We recommend starting with version 1.0.0, or using 0.y.z only for internal development, publishing to users starting with 1.0.0-alpha.

For continuous integration, a fourth component (Build) can be added: Major.Minor.Patch.Build.

Versioning Scheme Examples

Development
 1.0.0-1
 1.0.0-2
 1.0.0-3
 ...

Alpha versions
 1.0.0-alpha.1
...

Beta versions
 1.0.0-beta.1
...

Pre-releases
 1.0.0-rc.1
...

Release
 1.0.0

Versions in API

Versioning APIs ensures a seamless transition to new versions when adding features. For example, including the version in the REST API URL allows supporting multiple versions simultaneously.