create-release

create-release

Cut an annotated semver tag and publish a GitHub release with auto-generated notes.

Preconditions — verify ALL before doing anything

git status              # must be clean — stop if dirty, surface the diff
git branch --show-current   # must be on default branch (main/master)
git fetch origin && git status  # must be up to date with origin
gh auth status          # must succeed

If any check fails: stop and tell the user. Do not proceed.

Steps

1. Inspect actual tags — never rely on memory or CHANGELOG:

   git tag --sort=-v:refname | head -10
   

2. Review commits since last tag:

   git log <last-tag>..HEAD --oneline
   

3. Determine semver bump and state rationale — breaking = major, new feature = minor, fixes/polish = patch. Proceed immediately. Only pause to ask the user if the bump type is genuinely ambiguous (e.g. unclear whether commits are breaking).

4. Bump the repo's declared version — MANDATORY whenever a version field exists. This is the package/manifest version, not just a "user-facing app" version: a library, CLI, or installer package (e.g. one with a package.json "version") counts and must be bumped. Do not skip this because the repo "isn't an app." Grep the repo for version fields and update every match to X.Y.Z so the tag points at a commit carrying the correct version. Common locations (check all, update every match):

   File	Field
   package.json	"version"
   .claude-plugin/plugin.json	"version"
   app.json / app.config.js / app.config.ts	expo.version
   pubspec.yaml	version
   Cargo.toml	[package] version
   pyproject.toml	[project] version or [tool.poetry] version
   iOS *.xcodeproj/project.pbxproj	MARKETING_VERSION
   Android build.gradle	versionName

   • Leave native build numbers (buildNumber, versionCode, CURRENT_PROJECT_VERSION) alone unless the user asks.
   • If — and only if — no version field exists anywhere, skip silently and proceed to step 5.
   • Publish-on-release check (do this every time): inspect .github/workflows/ for a job that runs on release: published (e.g. npm publish). These jobs are almost always idempotency-guarded on the manifest version — if package.json still holds the previous version, the guard sees it already published and silently skips, so the release ships to GitHub but never reaches the registry. If such a workflow exists, bumping the manifest version in this step is what makes the publish actually fire; a mismatch between the tag and the manifest version is a bug.
   • If a version field exists, edit it, then commit and push before tagging:

     git commit -am "chore(release): bump version to X.Y.Z"
     git push origin <default-branch>
     

   • The tag must point at this bump commit — create the tag only after the commit and push succeed.