Track HiveGrid Cloud planning reference

hivegrid-cloud/docs/versioning.md

@@ -0,0 +1,47 @@
+# 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.