make-release

Release

Prepare and publish a new release for the wiswa 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. Bring the security policy's supported versions up to date. SECURITY.md is generated from security_policy_supported_versions in .wiswa.jsonnet, so edit that setting and the rendered table in the same commit. Editing SECURITY.md alone is reverted by the next regen. When NEW opens a series the table does not already list, replace the stale entry with the new one (a 0.5.1 release is covered by 0.5.x); a patch inside a series already listed does not need a change. Record which series you dropped. Dropping one ends its support.

6. 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.

7. Run the test suite with coverage. Run yarn test:cov. Every test must pass and total coverage must reach 100%, unless [tool.coverage.report] in pyproject.toml sets fail_under, which is then the threshold. Close a shortfall by writing the missing tests.

8. Confirm the last CI runs passed. Nothing is released on top of a red master. List the project's workflows with gh workflow list, and for each one that runs on pushes rather than only on tags, read its most recent run: gh run list --workflow <file> --branch master --limit 1. This covers the QA and test workflows and the packaging ones the project has - Flatpak, Snap, AppImage, and PyInstaller. Every conclusion must be success; read a failure with gh run view <run-id> --log-failed and fix it before releasing. A workflow that has never run is not a failure.

   Compare the head SHA of the newest tests run against git rev-parse HEAD. When they differ, the commits about to be released were never tested; say so, and let the user decide whether to push and wait before continuing.

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

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

11. 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.

12. 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. When the repository has no existing tags (the first release), also pass --yes: with no tag to compare against, cz asks "Is this the first tag created?" interactively, and a non-interactive shell aborts with EOFError before writing anything. --yes answers that prompt truthfully and changes nothing else about the substitution. If cz bump fails for any other 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.

13. 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.

14. Set the release date in CITATION.cff if the file exists. Replace the date-released value with today's date in YYYY-MM-DD form. cz bump does not update this field.

15. 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 version, the file is missing from [tool.commitizen].version_files - add it in .wiswa.jsonnet 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.

16. Run uv lock to update uv.lock with the new version.

17. Generate and verify man pages. Run yarn gen-manpage and then git add man/. Confirm the embedded .TH line shows version NEW and today's date; if not, stop and report.

18. 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 working tree.

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

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

21. 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/wiswa/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>.

22. 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.
• Never lower a coverage threshold, skip a test, or exclude a file from measurement to get past the pre-release checks. A shortfall is closed by writing tests or fixing the code.
• 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 working tree.
• 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 in .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.