48 lines
3.9 KiB
Markdown
48 lines
3.9 KiB
Markdown
# Versioning Policy
|
|
|
|
This project uses Semantic Versioning for public release decisions and records release notes in the root [CHANGELOG.md](../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 changes` note in the relevant release entry in [CHANGELOG.md](../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](../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](../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.
|