--- name: release_management description: Run disciplined software releases end to end: conventional commits that drive versioning, semantic versioning policy with deprecation rules, machine-generated changelogs, staged rollout gates from CI to production, and release notes that tell users whether upgrading is safe. Use when cutting a release, setting up release automation, choosing a version number, writing release notes, or planning a rollout. --- # Release Management ## Purpose Turn releases from a stressful event into a routine: every change carries a machine-readable kind, the kind picks the version number, the changelog writes itself, each environment promotes through an explicit gate, and the release note answers the only three questions users have: what changed, who is affected, and whether upgrading is safe. Covers the lifecycle from commit to published release. The traffic mechanics of a rollout (canary, blue-green, automatic rollback) live in the `deploy-safety` skill; this skill decides what gets released, how it is numbered, and when it moves forward. ## Workflow 1. **Enforce commit kinds from day one.** Every commit lands as `[optional scope][!]: ` per Conventional Commits 1.0.0: `feat` for a new capability, `fix` for a corrected defect, and conventional others (`docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`). Breaking changes get `!` before the colon or a `BREAKING CHANGE:` footer. The description says what changed and why in one specific sentence; it never restates the type alone. Run `bin/commitlint.py` in CI and on any commit the agent authors to catch malformed messages before they merge. 2. **Let the commits pick the version.** With SemVer 2.0.0: `fix` and `perf` bump patch, `feat` bumps minor, any breaking change bumps major, and everything else bumps nothing. Below 1.0.0 there is no compatibility promise, so conventional tooling bumps minor on `feat` and patch on everything else. One version number is never reused, and a released version's contents never change. Full policy in `references/versioning-policy.md`. 3. **Deprecate before you remove.** Mark the old behavior deprecated in one minor release with a migration note in the changelog, then remove it in a later release with a major bump. Never surprise-removal: a silent removal reads as a bug, not a decision. 4. **Generate the changelog, don't write it.** Use the commit kinds to build Keep a Changelog sections (Added / Changed / Deprecated / Removed / Fixed / Security). Tooling choices and config notes live in `references/changelog-guide.md`; whatever the tool, the release notes a user reads are a hand-written summary on top, not the raw dump. They answer: what changed, who is affected, is upgrading safe, and what action (if any) is required. 5. **Gate every stage.** A release moves dev -> staging -> production only when the stage's gate passes: builds green, tests green, database migrations are expand-compatible (old code still runs against new schema), docs updated for user-visible change, security review for auth/crypto/dependency changes. A gate that cannot fail in practice is decoration; check the log for the last time it actually blocked something. 6. **Roll out progressively, watch explicitly.** Choose the rollout shape on operational grounds (progressive steps 1% -> 5% -> 25% -> 100% for risky or high-traffic changes; direct promotion for small, low-risk ones). Each step defines its guardrail metrics with explicit abort thresholds before the step starts. Never promote on vibes; a step advances on passing gates, not a person watching a dashboard. The mechanics (how traffic splits, how rollback fires) belong to `deploy-safety`; this skill owns the decision and the checklist in `references/rollout-gates-checklist.md`. 7. **Have a hotfix lane.** A hotfix is the same pipeline with a faster gate: minimal review (one approver), same CI, same changelog entry marked as patch, and a forward-merge so the fix lands on main too. If the hotfix lane skips steps the normal lane requires, those steps are probably theater. 8. **Stabilize after release.** Tag the release in git, publish notes, archive the build record, clean up stale feature flags and old deployment targets from the rollout, and record what the gates caught. The release is not done when users have it; it is done when the next release starts from a clean state. ## Output Contract - A commit lint result (clean or a list of messages to fix) when authoring or reviewing commits. - A version number with the rule that produced it (e.g. "1.4.0: feat commits, no breaking changes"). - A changelog entry grouped by kind with dates and migration notes where applicable. - A gate checklist per stage with pass/fail and the evidence for each line. - A rollout decision: shape, guardrail metrics with abort thresholds, and the rollback lever. - Release notes that state what changed, who is affected, upgrade safety, and required actions. ## Operating Rules 1. A version bump is a contract with downstream users, not a celebration of internal effort. Number what changed for them. 2. If a gate cannot name the last release it blocked, assume it is decoration and fix it before the next release. 3. Never reuse a version number and never mutate a released version. A wrong release gets a new number, not an edit. 4. Rollback beats hotfix when users are already affected; fix forward only when the blast radius is contained and the fix is tested. 5. Database and schema changes roll out expand-contract: the new schema must keep old code running while both versions are live. 6. Release notes are written for the integrator deciding whether to upgrade. Internal effort ("we refactored the auth module") goes in the changelog body, not the headline. 7. If quality and cadence conflict, the release waits. A weak release shipped on schedule is a scheduled incident.