NotAlterra/skills/release-workflow/SKILL.md

Release Workflow

Versioning, release checklist, signing, and push conventions.

Versioning

Bump	When	Example
PATCH	Bug fix or small polish after a release	v0.3.1 → v0.3.2
MINOR	New feature or significant restructure	v0.3.x → v0.4.0
MAJOR	Breaking change (1.0+ only)	1.0.0 → 2.0.0

• Version in the project manifest matches the latest release tag
• Tags are created at release time, not per-commit
• Multiple commits can happen between tags

Draft Release Cycle

commit → push → tag v0.x.y → CI builds draft → user tests → publish

No release goes live without the user testing the draft first.

Release Checklist

Before signing a release tag:

• Impact analysis completed — all call sites for new/changed functions
• All tests pass
• Linter passes with zero warnings
• CHANGELOG.md has an entry for the new version
• Working tree is clean — no uncommitted changes
• Release notes file is updated for the new version

After CI completes:

• Download draft binaries from the releases page
• Test on target platform — basic workflow, key features
• Click Publish release on the hosting platform when satisfied

Signing & Push

• Commit with --no-gpg-sign (avoids GPG passphrase hang in non-interactive terminals)
• Sign once. Wait for CI to go green on the unsigned commit, then amend with --gpg-sign + force-push. Do not amend between CI runs — each amend creates a new SHA, which triggers a new CI run and leaves stale Pages deployments that block the next run.
• Passphrase typo protection. Run git commit --amend --gpg-sign --no-edit alone first. If the passphrase is wrong, only that command fails — the force-push, tag, and push don't run on a broken state. Verify with git verify-commit HEAD before proceeding with the remaining commands.
• Normal push for fast-forward commits
• --force-with-lease for amended commits or tag refreshes
• Start from a clean tag. Before re-tagging, always delete the old tag locally AND remotely (git tag -d v0.x.y && git push --delete origin v0.x.y). If the old tag still exists, git tag -s will fail with "tag already exists" and you'll end up with a tag pointing to the wrong commit.
• If force-pushing, delete old tag and re-tag after the new commit lands
• Tag once, push once. Re-signing an existing tag pushes a new SHA and triggers another CI run with the same deployment conflict risk.

Release Notes

• Release notes file contains only the current version's changes
• Historical release notes on the platform are cleaned per-release