Bump version — cut a termio release

termio is trunk-based: a release is nothing but a vX.Y.Z tag on main. Pushing the tag fires .github/workflows/release.yml (the Release workflow), which signs, notarizes, packages the DMG, updates the Sparkle appcast, and uploads to Cloudflare R2. There is no merge and no release branch.

Follow these steps in order. Stop and report if any precondition fails — never force past a failed check.

1. Preconditions

git switch main
git pull --ff-only
git status --short          # release-relevant work must be committed
git rev-parse --abbrev-ref HEAD    # must print: main

• Must be on main and even with origin/main (the tag ships whatever main points at right now).
• The working tree may have unrelated untracked scratch files, but anything meant for this release must already be committed and pushed.

2. Pick the next version

Read the current version and compute the next one:

git tag --list 'v*' --sort=-v:refname | head -1     # e.g. v0.13.1

Decide X.Y.Z (semver, no v when talking, v in the tag):

• Explicit version from the user (e.g. "0.14.0") → use it verbatim.
• A bump keyword → apply it to the latest tag: patch (0.13.1→0.13.2), minor (0.13.1→0.14.0), major (0.13.1→1.0.0).
• Nothing specified → propose the bump you believe fits (termio has used minor for features, patch for fixes) and confirm the number with the user before tagging.

The version must only ever go up — the build number is git rev-list --count HEAD, and Sparkle treats a lower CFBundleVersion as older, which breaks auto-update. Never reuse or lower a version.

3. Write the changelog entry

The site's changelog is web/landing/src/data/changelog.ts, newest entry first. Add the entry for the version you are about to tag before tagging — the Docs workflow fails once a tag exists without one, and a changelog that trails the releases makes the site read as abandoned.

gh release view "v$PREVIOUS" --json body -q .body     # what shipped since

Write it in the file's voice: a title naming what the release is remembered for, then short user-facing new / improved / fixed lines — what changed, not how. Skip a release whose only changes were docs, deps, or the landing page.

cd web/landing && pnpm docs:check     # must pass before you tag

4. Tag and push

V=0.14.0                       # the version you settled on
git tag "v$V"
git push origin "v$V"

That push is what triggers the release. Nothing else in the repo needs editing — the tag is the version.

5. Watch the Release workflow

gh run watch --repo termio-sh/termio \
  "$(gh run list --repo termio-sh/termio -w Release -L1 --json databaseId -q '.[0].databaseId')"

Report green/red to the user. If it fails, diagnose from the run log; the troubleshooting table is in docs/runbook/macos-release-runbook.md.

6. Verify (when green)

V=0.14.0
curl -sI https://downloads.termio.sh/termio.dmg     | head -1   # 200
curl -sI https://downloads.termio.sh/v$V/termio.dmg | head -1   # 200
curl -s  https://downloads.termio.sh/appcast.xml | grep -i shortVersionString | head -1

The newest appcast item should advertise the new version. Full verification (staple check, Gatekeeper, Sparkle end-to-end) lives in the runbook.

Re-running a failed release

If the build failed for an infrastructure reason (a secret, a flaky runner) and main is unchanged, delete and re-push the same tag — the version must not go backwards:

git push --delete origin "v$V" && git tag -d "v$V"
git tag "v$V" && git push origin "v$V"

If code had to change to fix it, that's a new commit on main, so cut the next version instead of reusing the tag.

Notes

• iOS releases are separate (.github/workflows/ios.yml + TestFlight); this skill is the macOS tag flow only.
• This skill does not commit anything. Land the release's code on main first (directly or via a merged PR), then run this.