Raw view: Release Cut and Notes

No invisible, zero-width, or bidi-control characters detected.

# Release Cut and Notes

Cut a release from `{{RELEASE_BRANCH}}`. Versioning scheme: {{VERSIONING_SCHEME}} (for example, semver or calver). Changelog file: `{{CHANGELOG_PATH}}`. Verification: `{{TEST_COMMAND}}`. Project-specific checklist, if any: {{RELEASE_CHECKLIST}}.

Nothing in this workflow pushes a tag or publishes an artifact without an explicit go-ahead at the marked stop point. Everything before that is reversible.

## Phase 1: Verify the tree

1. Confirm you are on `{{RELEASE_BRANCH}}`, the working tree is clean, and the local branch matches the remote (`git fetch` then compare). If not, STOP and report; releasing from a stale or dirty tree is the most common release mistake.
2. Confirm CI is green on the exact commit you are releasing. Record the CI run reference. If CI is red or pending, STOP.
3. Run `{{TEST_COMMAND}}` and the build locally. Record results. A local green does not replace CI; it catches environment-specific surprises.
4. Find the last release tag. Record its name and commit.

**Artifact:** `RELEASE-<pending>.md` with branch, commit SHA, CI reference, last tag.

## Phase 2: Review the changes

5. List every commit between the last tag and HEAD. For merge-based repositories, list merged PRs instead, with titles and links.
6. Classify each change: breaking, feature, fix, security, internal (no user-visible effect). Read the PR or commit body when the title is ambiguous; do not classify from the title alone.
7. Search the changes for anything the release must call out: migrations, config or env var changes, dependency major bumps, removed features, changed defaults. Record each with the PR reference.
8. Determine the version from the classification and {{VERSIONING_SCHEME}}: any breaking change bumps major (or whatever the scheme defines); otherwise feature bumps minor; otherwise patch. For pre-1.0 or calver, apply the scheme's rules and say which rule you applied.
9. **STOP POINT.** Present the change list with classifications, the callouts from step 7, and the proposed version. Wait for confirmation of the version number; this is a human decision.

**Artifact:** classified change list and proposed version in the release file.

## Phase 3: Prepare the release commit

10. Write the release notes from the classified list, user-facing: breaking changes first with required actions; then security; then features; then fixes. Drop internal changes. One line per change, leading with what the user can now do or no longer suffers. Keep PR references at the end of each line if the project's changelog does that.
11. Update `{{CHANGELOG_PATH}}`: add the new version section with the date, in the file's existing format. Do not reformat earlier sections.
12. Update the version wherever the project stores it (manifest, version file, constants). Search for the old version string to find every location; record each.
13. Work through {{RELEASE_CHECKLIST}} if provided (docs version switcher, API docs regeneration, migration guide). Record each item done or not applicable.
14. Run `{{TEST_COMMAND}}` and the build again. **Check:** green; version string appears correctly in the built artifact if the build embeds it.
15. Commit with message `release: <version>`. Do not tag yet.

**Artifact:** the release commit; updated changelog; release file updated with every file changed.

## Phase 4: Tag and publish (go-ahead required)

16. **STOP POINT.** Present the release commit diff, the notes as they will be published, and the exact commands you will run next (push, tag, publish). Wait for an explicit "go".
17. Push the release commit. Create the tag in the project's format (`v1.4.0`, `1.4.0`, `2026.10.16`) pointing at that commit, annotated with the version. Push the tag.
18. If publishing is automated by the tag (CI release job), watch it to completion and record the artifact URLs. If publishing is manual, run the documented publish command once and record the output.
19. **Check:** the published artifact's version matches; the release page or registry shows the notes; a fresh install of the published artifact works for one smoke test.

## Phase 5: Hand off

20. Complete the release file with: version, tag, commit, artifact URLs, the notes as published, the rollback procedure (previous tag and the command to redeploy or republish it; any migration that must be reversed), and the first things to watch (dashboards, error rates) in the hour after release.
21. Post the notes to the project's announcement channel if the checklist calls for it, as a draft for a human to send unless told otherwise.

**Final artifact:** `RELEASE-<version>.md` and the published release.

## Rules throughout

- Never force-push, delete a tag, or rewrite history during a release. If something is wrong after the tag exists, cut a new patch release.
- Never include a commit in the notes that you have not seen in the range.
- If any check fails after Phase 3, revert the release commit locally and start from Phase 1; do not patch forward on the release commit.