release

name: release description: Create a release PR with version bump, then auto-tag after merge

Create a release PR that bumps the version and updates the changelog. After the PR is merged, the tag-release.yml workflow will automatically tag the release, trigger cargo publish, and bump to the next development version.

Arguments

The skill accepts a version level argument:

• patch - 0.0.1 -> 0.0.2
• minor - 0.0.1 -> 0.1.0
• major - 0.0.1 -> 1.0.0
• Or an explicit version like 0.2.0

Example: /release minor

Steps

1. Verify prerequisites:

   • Must be on main branch
   • Working directory must be clean
   • Must be up to date with origin/main

   git fetch origin
   if [ "$(git branch --show-current)" != "main" ]; then
     echo "Error: Must be on main branch"
     exit 1
   fi
   if [ -n "$(git status --porcelain)" ]; then
     echo "Error: Working directory not clean"
     exit 1
   fi
   if [ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]; then
     echo "Error: Not up to date with origin/main"
     exit 1
   fi
   

2. Run local checks:

   cargo clippy --all-targets --all-features -- -D warnings
   cargo test --all
   

   If checks fail, stop and report the errors.

3. Determine the new version:

   • Read the current version from Cargo.toml
   • Calculate the new version based on the level argument (patch/minor/major) or use the explicit version provided

4. Create release branch:

   NEW_VERSION="X.Y.Z"  # from step 3
   git checkout -b release/v${NEW_VERSION}
   

5. Bump version in Cargo.toml:

   • Update the version = "..." field in the root Cargo.toml

6. Update CHANGELOG.md:

   • Move items from the "Unreleased" section to a new version section with the release date
   • Create a new empty "Unreleased" section
   • The changelog follows Keep a Changelog format
   • Ask the user if they want to review/edit the changelog before proceeding

7. Commit changes:

   CRITICAL: The commit message MUST start with release: v (no other words before the version). The tag-release.yml workflow matches startsWith(message, 'release: v') on the merge commit. When GitHub squash-merges a single-commit PR, the commit message becomes the merge commit message.

   git add Cargo.toml CHANGELOG.md
   git commit -m "release: v${NEW_VERSION}"
   

8. Push and create PR:

   git push -u origin release/v${NEW_VERSION}
   
   gh pr create \
     --title "release: v${NEW_VERSION}" \
     --body "$(cat <<EOF
   ## Release v${NEW_VERSION}
   
   This PR prepares the release of v${NEW_VERSION}.
   
   ### Changes
   - Version bump to ${NEW_VERSION}
   - Changelog update
   
   ### After Merge
   The tag-release workflow will automatically:
   1. Create git tag \`v${NEW_VERSION}\`
   2. Trigger CI + publish to crates.io
   3. Create a GitHub Release
   4. Bump to next development version (\`-alpha.0\`)
   
   ---
   See CHANGELOG.md for details.
   EOF
   )"
   

9. Report the PR URL to the user.

After PR Merge

When the PR is merged to main, the tag-release.yml workflow will:

1. Detect the version from Cargo.toml
2. Create and push the git tag vX.Y.Z
3. The release.yml workflow then runs CI and publishes to crates.io
4. Create a commit bumping to next dev version (e.g., 0.0.2-alpha.0)

Troubleshooting

• gh CLI not installed: brew install gh or see https://cli.github.com/
• Not authenticated with gh: gh auth login
• RELEASE_TOKEN secret missing: The tag-release workflow needs a PAT with contents: write stored as RELEASE_TOKEN in repo secrets (the default GITHUB_TOKEN can't trigger other workflows)
• CARGO_REGISTRY_TOKEN secret missing: The release workflow needs a crates.io API token stored as CARGO_REGISTRY_TOKEN in repo secrets