Release To Crates

<!-- Generated by rust-bucket v0.9.7. DO NOT EDIT BY HAND. -->

Make the version-bump edits directly. A release bump is a mechanical release-engineering operation, not feature work, so it does not need to be routed through whatever feature-delegation process the repo otherwise follows.

When to use

• The user asks to cut a release, bump the crate version, and/or publish to crates.io.
• Default the bump to patch for a non-breaking change. For a breaking change, choose minor/major per semver, then confirm the chosen level with the user before proceeding.

Hard gates (do not skip)

1. Merge gate — never merge the release PR without green CI; confirm with the user before merging unless they have explicitly pre-authorized an auto-merge.
2. Publish gate — cargo publish is irreversible: a crates.io version can never be re-uploaded or reused. Always run cargo publish --dry-run first, and only publish from a revision whose Cargo.toml version is confirmed not yet on crates.io.

Detect the environment first

These three facts drive every branching step below:

• VCS: if .jj/ exists → this is a colocated jujutsu/git repo; use jj for all commits/bookmarks/push, since raw git commands can corrupt jj state. Otherwise use plain git.
• Forge CLI: GitHub → gh. GitLab → glab. If the required forge CLI is not on PATH, stop and ask the human — do not improvise a web/manual flow.
• Crate name: read name from [package] in Cargo.toml.

Step 1 — Prepare: clean tree on updated trunk, reconcile versions

1. Ensure a clean working copy.
   • jj: jj st shows no changes; @ is empty (or run jj new).
   • git: git status clean.
2. Update trunk from the remote.
   • jj: jj git fetch; confirm main == main@origin.
   • git: git switch main && git pull --ff-only.
3. Establish the two sources of truth and assert they agree:
   • Local: version under [package] in Cargo.toml.
   • Published: query the registry (needs a User-Agent):

     curl -s -H "User-Agent: <crate>-release (<you@example.com>)" \
       https://crates.io/api/v1/crates/<crate> \
       | python3 -c "import sys,json; print(json.load(sys.stdin)['crate']['max_version'])"

     (A brand-new crate returns no crate object — treat as "never published".)
   • If Cargo.toml version != crates.io max_version, stop and report — the repo is in an unexpected state (a prior release was half-finished or the tree is stale).
4. Compute the next version (patch by default) and the branch name. Naming convention: <user>/bump-version-v<new-version> (e.g. danver/bump-version-v0.9.9).

Step 2 — Commit the bump on a release branch

1. Create the revision/bookmark with a message up front.
   • jj: jj desc -m "Bump version to <new>" (add a body explaining the bump); then edit, then jj bookmark create <user>/bump-version-v<new> -r @.
   • git: git switch -c <user>/bump-version-v<new>.
2. Edit Cargo.toml: set version = "<new>".
3. Regenerate the lock file: run cargo build. This updates the crate's own entry in Cargo.lock (easy to forget; the published package must carry a consistent lockfile).
4. Review the diff — it should touch only Cargo.toml and Cargo.lock, both just the version line. jj diff --git / git diff.
5. Commit message: imperative subject Bump version to <new>, no trailing period, no Conventional-Commits prefix; optional body noting it's a non-breaking patch release.

Step 3 — Push and open the PR

• Push the branch:
  • jj: jj git push -b <bookmark> --allow-new (new bookmarks need --allow-new).
  • git: git push -u origin <branch>.
• Open the PR via the forge CLI:

  gh pr create --base main --head <branch> --title "Bump version to <new>" \
    --body "Patch release of \`<crate>\`. Non-breaking; bumps Cargo.toml and Cargo.lock
            from <old> to <new> in preparation for publishing to crates.io.
            Last published version: <old>."

Step 4 — Wait for CI to go green (merge gate)

• Watch checks until they complete; the watch exits non-zero if any fail:

  gh pr checks <pr> --watch --interval 30

• Confirm the final state is mergeable:

  gh pr view <pr> --json state,mergeable,mergeStateStatus

• If any check fails: stop, report the failing check, and do not merge.

Step 5 — Merge (confirm with the human)

• Unless the user pre-authorized auto-merge, confirm before merging.
• Merge matching the repo's history style (this repo uses merge commits):

  gh pr merge <pr> --merge

• Verify state=MERGED.

Step 6 — Re-sync trunk and stage a clean publish revision

• Pull the merged trunk:
  • jj: jj git fetch; then jj new main -m "Publish <crate> <new> to crates.io".
  • git: git switch main && git pull --ff-only.
• Sanity-check: grep '^version' Cargo.toml shows <new> (the merge brought the bump in).

Step 7 — Publish (publish gate)

1. Dry run — validates packaging and runs the verification build without uploading:

   cargo publish --dry-run

   Warnings about test files "not included in the published package" are benign when those tests are excluded by the include list in Cargo.toml.
2. If the dry run is clean, publish for real:

   cargo publish

   (Requires a crates.io token: cargo login, or CARGO_REGISTRY_TOKEN in the env.)
3. Verify it went live: re-query the registry and confirm max_version == <new>.