Release

Prepare and publish a new release for the expert-rotary-phone project.

You manage the release process: update the changelog, determine the version bump, run pre-commit checks, bump the version, and push, and align GitHub release notes with the changelog.

Workflow

1. Review changes since last tag. Run git log $(git describe --tags --abbrev=0)..HEAD --oneline to see all commits since the last release.

2. Update CHANGELOG.md. Add entries under [Unreleased] if not already present. Use the appropriate sections: Added, Changed, Fixed, Removed.

3. Determine the version bump based on Semantic Versioning:

   • patch: bug fixes, dependency updates, documentation changes.
   • minor: new features, new commands, new public API additions.
   • major: breaking changes to public API, removed commands/functions.

4. Create a new version header below [Unreleased], moving the unreleased content under it. Format: ## [X.Y.Z] - YYYY-MM-DD. Leave [Unreleased] empty above it.

5. Launch agents in parallel before bumping:

   • copy-editor - to fix prose in the changelog entries.
   • qa-fixer - to format and fix any lint/spelling issues.

6. Sync repo state back to .wiswa.jsonnet. Run the wiswa-sync agent so every hand edit to a Wiswa-managed file since the last regen is reflected in .wiswa.jsonnet. Any release-time discoveries (for example a version_files entry that was missing) must round-trip so the next regen reproduces them.

7. Run pre-commit run -a outside the sandbox to ensure all hooks pass. The hooks write across the worktree, which the sandbox's read-only mount blocks. Fix any issues before proceeding.

8. Record the current HEAD before bumping: git rev-parse HEAD (save this as PRE_BUMP_REF).

9. Pre-scan version_files for collision risk. Note OLD (the current [tool.commitizen].version) and NEW (the post-bump version for the selected increment). For each entry in [tool.commitizen].version_files, run rg --fixed-strings --line-number 'OLD' <file> (or grep -nF 'OLD' <file>). Exactly one match is the canonical version field cz is meant to bump. Every other match is a collision candidate: cz uses plain string substitution, so any substring OLD in the file is replaced with NEW, regardless of context. Save the candidate list (file, line number, full pre-bump line) so the matches can be reverted after the bump. The classic example: OLD 0.0.0 and NEW 0.0.1 rewrite a "some-dep": "10.0.0" line into "some-dep": "10.0.1" even though 10.0.0 is unrelated to the project version.

10. Run cz bump --files-only --increment {MAJOR,MINOR,PATCH} with the appropriate increment. This only updates version strings in files without committing or tagging. Never pass --changelog or -ch to cz bump. If cz bump fails for any reason:

    1. Restore the repository to the pre-bump state: git checkout -- .
    2. Stop work immediately and alert the user. Do not attempt to work around the failure.

11. Revert accidental bump collisions. For every collision candidate recorded in the pre-scan, open the same file:line and confirm whether cz rewrote a substring inside an unrelated value (for example 10.0.0 → 10.0.1). If so, restore that line to its pre-bump content; leave the canonical version-field match in its post-bump state. If you are unsure whether a change is intended, prefer to revert and stop with a report rather than ship the bump with a corrupted dependency or transitive version.

12. Verify version-bound and source-bound files. Stop and report if any check fails:

    • CITATION.cff if present: version matches NEW and date-released equals today's date. If cz bump did not update either, the file is missing from [tool.commitizen].version_files - add it, rerun wiswa-sync, and restart the bump.
    • Flatpak manifest (flatpak/**, any *.flatpak.{json,yaml}) if present: every version reference is updated to NEW (cz must drive this through version_files - fix the configuration as above if it did not), and every sources entry pointing at this repository uses tag: vNEW with a fresh commit: SHA where applicable. No local path: sources, no moving branch.
    • Snapcraft (snap/snapcraft.yaml or top-level snapcraft.yaml) if present: every version reference and every part's source-tag: equal NEW / vNEW. source: points at the remote repository, never a local path. Same version_files rule for cz.

13. Commit the version bump outside the sandbox. Stage all changed files and commit with git commit -S -s -m 'bump: vOLD → vNEW' (replace OLD/NEW with actual versions). Run outside the sandbox because the pre-commit hooks invoked by the commit need to write across the worktree.

14. Create a signed tag. Run git tag -s vNEW -m 'vNEW' (replace NEW with the new version).

15. Push the commit and tag. Run git push && git push --tags.

16. Update GitHub release notes using gh (authenticated for this repository). After the tag is on the remote, automation may create the GitHub Release record later or as a draft; do not skip this step when a draft exists.

    • Wait for the release: Poll until gh release view vNEW exits successfully, including when isDraft is true. Use a short sleep between attempts and a sensible overall timeout; if the release never appears, stop and report the failure.
    • Body from CHANGELOG.md: Copy only the content for this version (from the first ### Added, ### Changed, ### Fixed, or ### Removed under that version through the line before the next ## [ version header). Do not include the ## [X.Y.Z] - YYYY-MM-DD heading line. For GitHub's layout, promote each of those subsection headings from ### to ## (### Added → ## Added, and the same pattern for Changed, Fixed, and Removed).
    • Wrapping within list items: Undo changelog hard-wraps inside one bullet: when a list line ends with a single newline and the following line continues the same item (for example an indented continuation), join them with one space so - item with long sentence plus line 2 reads as - item with long sentence line 2. Do not join across a paragraph break: leave any run of two or more consecutive newlines (\n\n or more) unchanged.
    • Full Changelog line: After the body, append one blank line, then exactly: **Full Changelog**: https://github.com/Tatsh/expert-rotary-phone/compare/vPREV...vNEW where vNEW is this release's tag. Set vPREV to the tag of the most recent other GitHub release (for example from gh release list, ordered by recency, skipping vNEW). If no earlier release exists on GitHub, fall back to the previous version in CHANGELOG.md immediately below this entry, or the git tag that precedes vNEW.
    • Apply: Write the combined Markdown to a file (for example under .wiswa-ci/) and run gh release edit vNEW --notes-file <path>.

17. Monitor CI until the release is undrafted. On GitHub, the release pipeline triggered by the tag push un-drafts the GitHub Release on success. Poll runs created at or after the push (use gh run list --branch vNEW and/or per-workflow filters; ignore older runs) on a short sleep until every post-push run reaches a terminal status and gh release view vNEW --json isDraft -q .isDraft returns false. Cap the loop with a sensible overall timeout. On all-green and undrafted, report the release URL and stop.

    If any post-push run failed, recover as follows:

    1. Alert the user with the failing run URLs and a one-line summary of the workflow and job that failed.
    2. Fetch the failing logs with gh run view <run-id> --log-failed (or --log for the full transcript) and read them to identify the root cause.
    3. Delete the broken release and tag. Run gh release delete vNEW --yes, git push origin :refs/tags/vNEW, and git tag -d vNEW.
    4. If the release was already un-drafted before the failure surfaced, do not reuse vNEW after the cleanup; a published release is part of the public history. Bump one more patch level so the recovery release is vNEW+1, leaving the failed tag as a recorded mistake.
    5. Apply the fix if the logs make the root cause clear, as a normal commit (separate from the original bump commit). Then restart from the version-bump step with the same OLD→NEW (or OLD→NEW+1 in the premature-undraft case).
    6. If the cause is unclear, stop and hand back to the user with the logs and the cleanup state.

Rules

• Never use --no-verify or skip hooks.
• Never force-push.
• If any step fails, stop and report the error. Do not continue the release process.
• The [Unreleased] section must always exist at the top of the changelog after the release.
• Run pre-commit run -a and the version-bump git commit outside the sandbox; both need write access across the worktree.
• Flatpak manifests and snapcraft.yaml at release time always build from the about-to-be pushed tag, never from a local path or moving branch.
• Never hand-patch a version reference in CITATION.cff, a flatpak manifest, or snapcraft.yaml to compensate for a missing [tool.commitizen].version_files entry. Fix the configuration, run wiswa-sync so the fix reaches .wiswa.jsonnet, then restart the bump.
• cz bump --files-only is plain string substitution, not pattern-aware. Always pre-scan every version_files entry for OLD substrings before bumping, and revert non-canonical matches afterwards so unrelated literals like 10.0.0 are not corrupted into 10.0.1.
• A release is not complete until every post-push CI run reaches a terminal status and the GitHub Release is un-drafted. If recovery requires deleting a release that was already un-drafted, bump one more patch level instead of reusing the failed tag - a published release is part of the public history and must not be silently replaced.