Versioning

There are various ways to document the state of a repository. To improve both readability and functionality, we highly recommend adopting a consistent structure when describing its state. A key element of this structure can be a version identifier.

Versioning provides a logical framework for labeling specific states of a repository. It offers a structured way to describe these states, though the exact method may vary depending on the versioning approach used. Many different options exist, each with their own logic.

Choosing the most appropriate versioning approach can be somewhat subjective. However, certain methods are more commonly adopted than others. Here, we present one of the most popular approaches: SemVer.

Semantic Versioning

In short, SemVer is a versioning system that uses a three-part number (\(X.Y.Z\)) to track changes to your software.

(1)\[\underset{\overbrace{\text{Major}}}{\bf{X}}.\overset{\underbrace{\text{Minor}}}{\bf{Y}}.\underset{\overbrace{\text{Patch}}}{\bf{Z}}\]

Major

Increment when you make breaking changes or significant updates.

Minor

Increment when you add new features or functionality.

Patch

Increment when you make bug fixes or minor updates.

Benefits

• Integrates perfectly with git tag:

  git tag -a X.Y.Z -m 'short description of state'
  

• Easy to understand and communicate changes to your software.

• Helps users and developers understand the impact of updates.

• Simplifies dependency management and versioning.