release

Prompt file imported from phenobarbital/querysource (.claude/commands/release.md). Fill in {{arguments}} before use. Copyright stays with the author.

/release — QuerySource Release via gh

Arguments: {{arguments}}

Drive a release of querysource: bump the version on dev, open (and, on confirmation, merge) the dev → main PR, then — only after an explicit yes — run gh release create on main. Creating the release fires .github/workflows/release.yml, which builds the wheels (cibuildwheel + maturin, Python 3.10–3.13) and uploads to PyPI.

Usage

/release patch                    # 4.5.15 -> 4.5.16
/release minor                    # 4.5.15 -> 4.6.0
/release major                    # 4.5.15 -> 5.0.0
/release 4.5.16-1                 # explicit version (hotfix-style suffix, as 4.5.11-1)
/release patch --dry-run          # show the plan, touch nothing
/release patch --no-release       # bump + push + PR, stop before gh release
/release patch --draft            # create the GitHub Release as a draft (no publish)
/release --publish-only 4.5.16    # version already on main: only create the release
/release patch --notes-from-changes   # notes from CHANGES.rst "Unreleased" instead of --generate-notes

How versioning works here

• Single source of truth: __version__ in querysource/version.py (pyproject.toml has dynamic = ["version"] → version = {attr = "querysource.__version__"}). querysource/_version.py is generated by setuptools_scm and untracked — never edit or commit it.
• Tags are the bare version (4.5.15, no v prefix). They are created by gh release create itself, pointing at main.
• Branch flow: the bump commit lands on dev, reaches main through a dev → main PR (merge commit), and the release targets main.
• Release notes: --generate-notes (the "What's Changed" / "Full Changelog" format used by every previous release).
• PyPI never allows re-uploading a version. A broken release is fixed with a new version, never by deleting and recreating the same one.

Step 1 — Preflight (read-only)

1. Parse {{arguments}}: exactly one of patch, minor, major, an explicit X.Y.Z[-N], or --publish-only X.Y.Z. If missing or ambiguous, ask — never default to patch.
2. Tooling and remote state:

   gh auth status
   git fetch origin --tags --prune

   If gh is not authenticated, stop and tell the user to run ! gh auth login.
3. Location — never release from a feature branch or a worktree:

   git rev-parse --abbrev-ref HEAD && git rev-parse --show-toplevel

   Abort if HEAD is not dev (or main for --publish-only) or the toplevel is under .claude/worktrees/.
4. Clean tracked tree (untracked files are ignored — they never enter the release commit):

   git status --porcelain --untracked-files=no

   If non-empty, abort: "Commit or stash first — the release commit carries only querysource/version.py (and CHANGES.rst if requested)."
5. Branch sync:

   git rev-list --left-right --count dev...origin/dev     # must be "0 0" (or ahead-only)
   git log --oneline --no-merges origin/dev..origin/main  # commits on main missing from dev

   • dev behind origin/dev → abort, ask the user to git pull --ff-only.
   • main has non-merge commits that dev lacks → warn: the PR will not be a clean fast path; suggest refreshing dev from main first (as PR #595 did) and ask whether to continue.
6. Current versions:

   grep -E "^__version__" querysource/version.py
   git show origin/main:querysource/version.py | grep -E "^__version__"
   gh release list -L 3

   Compute NEXT from the dev version and the bump part. Then refuse if it already exists anywhere:

   git rev-parse -q --verify "refs/tags/$NEXT" && echo "TAG EXISTS"
   gh release view "$NEXT" >/dev/null 2>&1 && echo "RELEASE EXISTS"

   Also abort if NEXT is not greater than the latest release tag.
7. Live SDD workers may merge/reset shared branches under you:

   ps -eo pid,etime,args | grep -i '[s]dd-worker'

   If one is live, warn and ask before continuing.

Step 2 — Plan

Show the plan and what landed since the last release:

LAST=$(gh release list -L 1 --json tagName -q '.[0].tagName')
git log --oneline --no-merges "$LAST"..origin/dev

Release plan
  Current (dev):   4.5.15      Latest release: 4.5.15
  Next:            4.5.16
  1. Commit "chore(release): bump version to 4.5.16" on dev, push
  2. PR dev -> main  ("Release 4.5.16"), merge on confirmation
  3. gh release create 4.5.16 --target main --generate-notes
  4. release.yml builds wheels and publishes to PyPI (~10 min)

If --dry-run was passed, stop here.

Step 3 — Bump on dev

1. Edit querysource/version.py: set __version__ = '<NEXT>' (keep single quotes — match the file). Touch nothing else.
2. Only if --notes-from-changes was passed: in CHANGES.rst, retitle the Unreleased / ========== heading to <NEXT> (YYYY-MM-DD) with a matching = underline and open a fresh empty Unreleased section above it. Show the diff and get approval before continuing.
3. Commit and push — stage explicit paths only, never git add .:

   git add querysource/version.py            # + CHANGES.rst if step 2 ran
   git diff --cached --name-only             # must list only those files
   git commit -m "chore(release): bump version to <NEXT>"
   git push origin dev

Step 4 — Land on main

1. Reuse an open dev → main PR if there is one, otherwise create it:

   gh pr list --base main --head dev --state open --json number,url
   gh pr create --base main --head dev --title "Release <NEXT>" \
     --body "Release <NEXT>. Merging publishes nothing by itself; the GitHub Release does."

2. Show the PR URL and the checks: gh pr checks <number>.
3. Ask for confirmation to merge. On yes:

   gh pr merge <number> --merge
   git fetch origin
   git show origin/main:querysource/version.py | grep -E "^__version__"   # must equal NEXT

   If the user prefers to merge on GitHub, stop here and tell them to run /release --publish-only <NEXT> afterwards.

If --no-release was passed, stop here and print that follow-up command.

Step 5 — GitHub Release (irreversible — confirm)

--publish-only X.Y.Z enters here directly, after Step 1 checks 1–4 and 6 (with NEXT = X.Y.Z, and requiring origin/main's version to equal it).

1. State plainly: "This creates tag <NEXT> on main and triggers release.yml, which uploads querysource <NEXT> to PyPI. PyPI does not allow re-uploading this version."
2. Ask for explicit confirmation. Never proceed on an implied yes.
3. Create the release:

   gh release create "<NEXT>" --target main --title "<NEXT>" --generate-notes --latest

   • --draft in {{arguments}} → add --draft (no workflow run until it is published from GitHub).
   • --notes-from-changes → write the new CHANGES.rst section to a scratch file and use --notes-file <file> instead of --generate-notes.
4. Watch the publish run:

   sleep 5
   RUN=$(gh run list --workflow release.yml -L 1 --json databaseId -q '.[0].databaseId')
   gh run watch "$RUN" --exit-status

   Run the watch in the background (it takes ~10 minutes) and report when it finishes. On failure, show gh run view "$RUN" --log-failed | tail -60.

Step 6 — Report

Release 4.5.16

  Version bump:  querysource/version.py  4.5.15 -> 4.5.16  (<sha> on dev)
  PR:            #<n> dev -> main  (merged / open)
  GH Release:    https://github.com/phenobarbital/querysource/releases/tag/4.5.16  (created / draft / skipped)
  PyPI:          release.yml run <id> — success / failed / running
                 https://pypi.org/project/querysource/4.5.16/

Error handling

Never

• git push --force to dev or main, or delete/move an existing tag.
• gh release delete of a published version to "retry".
• Edit or commit querysource/_version.py.
• Create the release before main contains the version bump.