3.9 KiB
Versioning Policy
This project uses Semantic Versioning for public release decisions and records release notes in the root CHANGELOG.md. Package-manager examples must stay aligned with the pinned pnpm@10.33.0 declaration in package.json; for focused verification use explicit commands such as pnpm exec vitest run scripts/verify-release-docs-baseline.test.mjs.
SemVer rules
Major versions
Increment the major version for any breaking change. A breaking change is any change that can require downstream code, configuration, deployment scripts, documented workflows, stored data expectations, or operator runbooks to change before an upgrade succeeds.
Major releases must include:
- A
Breaking changesnote in the relevant release entry in CHANGELOG.md. - Required migration steps and any known incompatible configuration or data assumptions.
- Rollback notes that explain whether downgrade is supported, blocked, or requires restoring data from backup.
Minor versions
Increment the minor version for backward-compatible features, new documented workflows, additive API or configuration capabilities, and deprecations that do not remove existing behavior.
Minor releases must include release notes for user-visible additions, operational changes, and deprecation notices. Additive changes should preserve existing defaults unless the changelog explicitly describes the changed default and why it is safe.
Patch versions
Increment the patch version for backward-compatible bug fixes, documentation corrections, dependency patching, and non-breaking reliability or security hardening.
Patch releases must not introduce breaking changes. If a fix requires a behavior change that downstream users must adapt to, treat it as a major change unless a documented compatibility path exists.
Breaking-change policy
Breaking changes cannot be silent. Before merging or releasing one, document the affected surface, migration path, rollback expectations, and verification evidence in CHANGELOG.md. Examples include removing an endpoint, renaming an environment variable, changing database semantics, tightening authorization in a way that rejects formerly valid usage, or changing a documented command contract.
Deprecation lifecycle
Deprecations should start in a minor release and appear under Deprecated in CHANGELOG.md. Each deprecation entry must state the replacement, the earliest planned removal version or release window, operational risk, and how maintainers will detect remaining usage. Removal happens in a major release unless the deprecated behavior is demonstrably unused and the changelog documents the safety rationale.
Release-note expectations
Every release entry must keep the Keep a Changelog categories: Added, Changed, Deprecated, Removed, Fixed, and Security. Empty categories should say that no changes were introduced for that category rather than leaving unfinished marker text. Release notes should include focused verification commands when useful, using explicit non-E2E examples such as pnpm exec vitest run scripts/verify-release-docs-baseline.test.mjs.
Rollback note expectations
For changes that affect deployability, data, configuration, or security posture, release notes must explain rollback behavior. State whether rollback is automatic, requires redeploying the prior artifact, requires a database backup restore, or is unsupported after a migration. If rollback requires manual operator action, describe the required evidence and the safest stopping point.
Verification boundary
Automatic release-documentation verification is limited to non-E2E checks: file/content assertions, focused lint where applicable, focused Vitest targets, and scripts that do not drive a live browser. Browser automation, production-like provider calls, and manual runtime journeys stay outside auto-mode and must be recorded as manual verification when they are needed.