Versioning and Release Policy Template (SemVer, CalVer, CRA)

Versioning and Release Policy: [Organisation or product line]

Policy that sets how [Organisation] numbers, releases, supports and retires its software: the versioning scheme (Semantic Versioning 2.0.0 or Calendar Versioning spec 26.0), release types and cadence, commit and changelog conventions (Conventional Commits 1.0.0, Keep a Changelog 1.1.0), support tiers and end-of-life windows, long-term support, security-fix backports, deprecation, publication and yanking. It includes the support-period duty of the EU Cyber Resilience Act (Regulation (EU) 2024/2847, Article 13(8) to 13(11) and 13(19), with the related points of Annex I, Part II) for products with digital elements. Replace every [bracketed] value and every row marked Example. The CRA parts are a documentation format, not legal advice: check the consolidated text and confirm scope with counsel.

Document control

Approvals

Revision history

Contents

1. Purpose, scope and principles
2. Roles and responsibilities
3. Policy statements
4. Versioning scheme
5. Release types and cadence
6. Commit conventions, changelog and release notes
7. Support tiers, LTS and end of life
8. Security fixes and backports
9. Deprecation and breaking changes
10. Publication, immutability and yanking
11. Exceptions and risk acceptance
12. Compliance measurement
13. Review cycle
14. Glossary and references

1. Purpose, scope and principles

1.1 Purpose

This policy makes version numbers a reliable promise. A consumer who reads a version must be able to tell whether an upgrade is safe, how long that version will receive fixes, and where the list of changes is. A team that ships must know which numbers it may use, how often it may release, and what it owes to customers on older versions.

1.2 Scope

The policy covers every artefact that [Organisation] publishes or deploys and that carries a version: libraries and SDKs, command-line tools, installable agents and appliances, container images, Helm charts and other deployment packages, mobile and desktop applications, and the release labels of continuously deployed services. It does not cover internal build numbers that never leave the pipeline, and it does not set HTTP API version numbers, which follow the API Versioning and Deprecation Policy (architecture/api-deprecation-policy).

1.3 Product inventory

1.4 Principles

• The source repository and its signed tags are the source of truth for what a version contains.
• A published version is immutable. A mistake is fixed by a new version, never by replacing the old one.
• Version numbers describe compatibility for consumers, not effort or marketing. Marketing names may exist alongside, but never instead.
• Support promises are public, dated and staffed.
• Security fixes reach every supported version, not only the newest.

2. Roles and responsibilities

R = responsible, A = accountable, C = consulted, I = informed.

3. Policy statements

4. Versioning scheme

4.1 Choosing a scheme

Decision for each product is recorded in section 1.3. A product that changes scheme MUST make the new numbers sort after the old ones (for example from 4.9.2 to 2026.10.0), and MUST state the change in its changelog and release notes.

4.2 Semantic Versioning rules

For products using Semantic Versioning 2.0.0 (semver.org):

1. The version has the form MAJOR.MINOR.PATCH, three non-negative integers without leading zeros.
2. The product MUST declare its public API in its documentation. Without a declared public API, compatibility claims are meaningless.
3. Increment PATCH for backward-compatible bug fixes, MINOR for backward-compatible new functionality or a deprecation, and MAJOR for any incompatible change to the public API. Lower components reset to zero when a higher one increments.
4. Major version zero (0.y.z) is initial development: anything may change. A product MUST reach 1.0.0 before it is offered to external customers under a support contract.
5. Treat the following as public API for compatibility purposes, in addition to the code interface: configuration file keys, CLI flags and exit codes, environment variables, on-disk and wire formats, and the minimum supported runtime (dropping a runtime version is a MAJOR change unless the runtime itself is end of life and this was announced under section 9; on an LTS train, section 7.3 applies).

4.3 Calendar Versioning rules

For products using Calendar Versioning (calver.org, spec 26.0):

1. Choose the format from the CalVer tokens: YYYY (full year), YY (short year), 0Y (zero-padded year), M and 0M (month), W and 0W (week of year), D and 0D (day), plus non-date parts such as MAJOR, MINOR and MICRO.
2. Spec 26.0 deprecates the MM, WW and DD tokens because a doubled letter is commonly read as two digits. Write 0M, 0W or 0D for zero-padded fields and M, W or D otherwise.
3. Zero-padded fields are not valid SemVer numbers. For artefacts published to a SemVer-only registry (npm, Cargo) use the non-padded tokens, for example YYYY.M.MICRO.
4. The date in the version is the date of the release cut, in UTC, not the deployment date.
5. A MICRO (or other non-date) segment starts at 0 for the first release in each date period and resets when the date part changes, so 2026.10.0 is the first release cut in October 2026.
6. Go modules: avoid CalVer. Go treats a major version of 2 or more as part of the module path, so every new year would need a new /vYYYY import path and an edit in every consumer.

4.4 Pre-release and build metadata

• Pre-release identifiers follow the patch number after a hyphen, for example 3.2.0-rc.1. They have lower precedence than the release, so 3.2.0-rc.1 sorts before 3.2.0.
• Allowed pre-release labels: alpha.N, beta.N, rc.N. Numbered identifiers sort numerically, so use rc.10 safely after rc.9.
• Build metadata follows a plus sign, for example 3.2.0+sha.4f2a9c1. Build metadata is ignored for precedence and MUST NOT be the only difference between two published artefacts.
• Pre-releases MUST be published to a pre-release channel (for example an npm dist-tag next) so that default installs never receive them.

4.5 Version source of truth and tags

5. Release types and cadence

5.1 Release types

5.2 Cadence

The release calendar for the next two quarters is published at [calendar link]. Moving a train date by more than [5] business days needs product owner approval and a note to customers on the support page.

5.3 Release flow

Each release runs the Release Checklist (dev/release-checklist). The checklist is per release; this flow is the policy view of it.

6. Commit conventions, changelog and release notes

6.1 Commit messages

Teams SHOULD write commits in Conventional Commits 1.0.0 form: <type>[optional scope][!]: <description>, with optional body and footers. The mapping to version increments is:

Only feat and fix and the breaking-change markers carry meaning in the specification; the other types and the Deprecated: and Security: footers are conventions of this policy. Squash merges MUST produce a compliant subject, because the squash commit is what tools read.

6.2 Changelog

• Each product keeps a CHANGELOG.md in Keep a Changelog 1.1.0 form: an Unreleased section at the top, then one section per version with an ISO 8601 date, newest first, and change groups Added, Changed, Deprecated, Removed, Fixed and Security.
• Entries are written for the consumer: what changed and what to do, not which file was edited. Use the Changelog template (dev/changelog).
• A yanked version stays in the changelog, marked [YANKED] after the date, with the reason (section 10.3).
• Generated drafts from commit messages are allowed; a human from the owning team MUST edit and approve the entry before release.

6.3 Release notes

Major and minor releases of products with external consumers have release notes written from the Release Notes template (dev/release-notes): highlights, breaking changes with migration steps, deprecations, security fixes with advisory and CVE references, and known issues. Patch releases MAY rely on the changelog entry alone.

7. Support tiers, LTS and end of life

7.1 Support tiers

7.2 Support windows by product

This table is the single source of truth for support windows. Sections 1.3, 7.3, 7.4 and the public support page restate it and MUST be updated in the same change when it changes.

Capacity check (Example): PRD-001 ships a major at most every 24 months (section 5.2) and supports each for 5 years, so at most three majors are supported at once (the current one and two in Security-only). PRD-003 ships a train every 36 months with a 5-year period, so at most two trains overlap, which matches the LTS limit in section 7.3. Recompute this check whenever the cadence or the period changes.

7.3 Long-term support (LTS)

• An LTS train is a major release line designated for long-term support. The first release of an LTS train is designated LTS on the day it is published, never retroactively.
• While a train is Active it receives minor and patch releases. Once the next LTS train ships, the previous train receives PATCH releases only (security fixes and critical defect fixes) until its support period ends. Features never backport into a train in Security-only support.
• At most [2] LTS trains of one product are supported at the same time. More trains multiply backport cost and test matrices; set the train cadence so that this limit holds (section 7.2 capacity check).
• Runtime and dependency support: an LTS train names the runtimes and operating systems it supports. When one of those reaches its own end of life, the product owner decides, under section 9, whether to keep it until the end of the train or drop it in the next LTS train. Dropping a runtime inside a train needs an exception under section 11.

7.4 EU Cyber Resilience Act support period

Regulation (EU) 2024/2847 (Cyber Resilience Act) applies in general from 11 December 2027; the reporting obligations of Article 14 apply from 11 September 2026. Check the consolidated text on EUR-Lex for current dates and any delegated acts. The provisions below are paraphrased from the Official Journal text. This is a documentation format, not legal advice.

Support period determination for each CRA product (the support period itself is set in section 7.2):

Vulnerability handling and reporting under Articles 13 and 14 are run through CRA Vulnerability Handling (security/cra-vulnerability-handling) and the PSIRT process (security/psirt-vulnerability-handling).

7.5 End-of-life process

1. The product owner proposes the EOL date and records it in the support lifecycle table at least the notice period in section 7.2 ahead.
2. Support informs affected customers through account contacts, the support page and, where available, in-product notices.
3. Release engineering marks the version line EOL in registries where supported (for example deprecation messages on packages) and on the download archive, with a pointer to the supported upgrade path.
4. On the EOL date, CI stops building the line, branch protection is kept, and the branch is archived read-only.
5. Within [10] business days after EOL, the product owner confirms the step list above in the revision history of the support page.

8. Security fixes and backports

8.1 Backport rules

1. A security fix is developed on the default branch first, unless the affected code exists only on older lines.
2. The PSIRT decides the affected version range and the target lines.
3. Fixes are cherry-picked to every affected release line in Active, Security-only or contracted Extended support.
4. Each backport ships as a PATCH release on its line, with a changelog Security entry referencing the advisory.
5. Coordinated release: all supported lines are published in the same release window, so the fix in one line does not disclose the vulnerability in another.

8.2 Targets

Severity ratings and exploitation context come from the Vulnerability Management Policy (security/vulnerability-management-policy) and the PSIRT process. Advisories use the Security Advisory template (security/security-advisory), and VEX statements follow the SBOM and VEX Policy (security/sbom-vex-policy).

8.3 When a backport is not possible

If a fix cannot be made safely on an older line (for example it needs a breaking change), the PSIRT and the product owner record an exception under section 11 with the compensating guidance for customers, and offer a free upgrade path to a fixed line. For CRA products this may use the Article 13(10) route, which covers only the remediation requirement of Annex I, Part II, point (2), is available only where later, substantially modified versions of the software have been placed on the market, and requires that users can move to the latest version free of charge and without extra costs to adapt their hardware and software environment. Record the decision and the evidence for each condition in the technical file; every other CRA duty, including disclosure of fixed vulnerabilities and the support period itself, still applies to the older line.

9. Deprecation and breaking changes

9.1 Rules

• A feature, option, interface or supported platform is deprecated in a MINOR release with a Deprecated changelog entry, documentation note and, where technically possible, a runtime warning naming the replacement.
• Removal happens only in a MAJOR release (SemVer products) or after the notice period (CalVer products), never in a patch.
• Each breaking change in a major release has upgrade notes with before and after examples and, where possible, an automated migration tool or codemod.

9.2 Notice periods

9.3 Breaking change register

10. Publication, immutability and yanking

10.1 Publication

• Releases are published only by the release pipeline identity; no personal tokens publish to production registries.
• Artefacts are signed and carry build provenance; SBOMs are produced as set in the SBOM and VEX Policy (security/sbom-vex-policy).
• Container images are referenced by digest in deployment manifests. Moving tags (latest, stable, 5) MAY exist for convenience but never for production deployment.

10.2 Retention and archives

10.3 Yanking and corrections

1. If a release is broken or dangerous, publish a corrected version immediately (PATCH + 1); never re-publish the same number.
2. Mark the bad version as yanked or deprecated in the registry where supported, so new installs avoid it while existing lock files still resolve.
3. Add [YANKED] and the reason to its changelog heading.
4. Delete an artefact only for legal reasons or leaked secrets, with release engineering and legal approval, and record it as an incident.

11. Exceptions and risk acceptance

An exception request states the policy statement affected (section 3), product and versions, reason, risk to consumers, compensating measures, and expiry date. Exceptions expire after at most [6] months and are reviewed in the next policy review.

Risk acceptance for exceptions that leave a known vulnerability unfixed on a supported line is recorded in the Risk Register (compliance/risk-register).

12. Compliance measurement

Worked example (Example): in Q3 2026 Corvid released 42 versions of PRD-001; 41 passed tag signature checks, so REL-M01 = 41 / 42 x 100 = 97.6%. The failure was a manual tag pushed during an outage and was recorded as an incident.

Results are reported quarterly to the engineering leadership review.

13. Review cycle

• Scheduled review every 12 months by the release engineering lead with the approvers listed in Document control.
• Early review when: a new product line is added; a major regulatory change applies (for example CRA delegated acts setting minimum support periods for a product category); a referenced specification publishes a new version (SemVer, CalVer, Conventional Commits, Keep a Changelog); an exception is renewed twice; or REL-M02 or REL-M05 misses target for two consecutive quarters.
• The review outcome is recorded in the revision history, even when nothing changes.

14. Glossary and references

14.1 Glossary

14.2 References

Standard and licence note

Based on Semantic Versioning 2.0.0 (semver.org, CC BY 3.0, by Tom Preston-Werner), Calendar Versioning spec 26.0 (calver.org, CC BY-SA 4.0), Conventional Commits 1.0.0 (conventionalcommits.org, CC BY 3.0) and Keep a Changelog 1.1.0 (keepachangelog.com, MIT), and on Regulation (EU) 2024/2847 (Cyber Resilience Act), Article 13(8) to 13(11) and 13(19) and Annex I, Part II, with NIST SP 800-218 (SSDF, a work of the United States Government) cited for context. Rules from these specifications are summarised in original wording; no specification text is reproduced. The CalVer token rules in section 4.3 are adapted from calver.org, whose page footer marks the site content CC BY-SA 4.0 (the site's source repository, github.com/mahmoud/calver, carries a separate BSD-style licence): if you redistribute an adapted version of that material, attribute calver.org and share it under the same licence. CRA provisions are paraphrased; check the consolidated text on EUR-Lex and any delegated or implementing acts before relying on them. This is a documentation format, not legal advice. Check the current official version of each specification before adopting this policy. Original text written for this collection. Template licence: MIT.