Versioning (SemVer)¶


What	The semantic versioning rules that branch names, tags, JIRA Releases, and app versions all share.
Owner	Engineering, enforced through branching and release discipline.
Triggers	Every release and hotfix.

Summary¶

We follow Semantic Versioning: MAJOR.MINOR.PATCH. One version number flows through everything: the JIRA Release, the Git release branch, the production tag, and the app version all match. Each release branch has a unique version, tagged only after all work is integrated and approved. Hotfixes increment the patch number. This single shared number is what makes the whole lifecycle traceable.

Full detail¶

The format¶

MAJOR.MINOR.PATCH, for example v1.3.0.

Part	Increment when
MAJOR	Incompatible or breaking changes.
MINOR	New, backward-compatible functionality.
PATCH	Backward-compatible fixes, including hotfixes.

Rules¶

Each release branch has a unique version (for example v1.4.0).
A release branch is tagged only after all work is integrated and approved, never before.
Ideally only one release branch is active at a time.
Hotfix versions increment the patch number: v1.3.0 becomes v1.3.1, then v1.3.2, and so on.
The version in the branch name MUST match the JIRA Release version, which MUST match the app version.

One number, everywhere¶

flowchart TD
    A[Decide version per SemVer] --> B[JIRA Release vX.Y.Z]
    B --> C[Git branch release/vX.Y.Z]
    C --> D[Tag vX.Y.Z at approval]
    D --> E[App version X.Y.Z in production]
    E --> F[Traceable end to end]

Why no version reuse¶

A closed version is frozen forever. New work always takes a new version, because reusing a number would create two different codebases claiming the same version, which breaks traceability and causes environment and regression problems. See JIRA & Release Management.

Example¶

A backward-compatible feature release moves v1.3.2 to v1.4.0. A later urgent production fix on top of it becomes v1.4.1 (patch increment) via a hotfix branched from tag v1.4.0. A future breaking API change would move to v2.0.0.