Release versioning
Purpose: A version scheme and branch model that keeps artefacts, tags and deployments unambiguous.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| All engineers | Daily branch/version hygiene |
Version scheme
SemVer-ish for a deployable product: MAJOR.MINOR.PATCH
| Segment | Bumped when |
|---|---|
| MAJOR | Breaking platform/content-structure changes (migration required) |
| MINOR | Normal feature releases (the default increment) |
| PATCH | Hotfixes on a released version |
One version for the whole release: the all package, embedded bundles and git tag carry the same number. Consumers of exported JSON get API stability signals from it too (JSON contracts).
Branch model (trunk-based, release-branched)
main ──●──●──●──●──●──●──▶ (always releasable; PRs land here)
└─ release/2.14 ──●──▶ (cut at code freeze; stabilisation only)
│ └─ tag v2.14.0 → artefact 2.14.0 → prod
└─ hotfix commits → v2.14.1 (cherry-picked back to main)- Feature branches are short-lived (days); long-lived feature work hides behind config flags on main instead.
- Release branches accept fixes only; features wait for the next cut. This is what makes the hotfix process sane.
- Tags are immutable and are what pipelines build from; "rebuild of v2.14.0" is a contradiction — that's v2.14.1.
What gets a changelog entry
Author-visible changes (dialogs, templates, styles), API/JSON shape changes, config keys added/renamed, operational behaviour changes. Written for the two audiences who actually read it: content ops and the on-call engineer.