Releasing a New Version

Overview

Bump versions, tag, and publish a GitHub Release with an auto-generated changelog. All version sources must stay in sync.

Version Sources (must match)

Steps

1. Determine version bump

Check commits since last tag:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Apply semver: patch for fixes, minor for features, major for breaking changes.

2. Update version in both JSON files

Edit plugin.json and marketplace.json to the new version string. Both must match exactly.

3. Commit version bump

git add .claude-plugin/plugin.json .claude-plugin/marketplace.json
git commit -m "chore: bump version to X.Y.Z"

4. Create tag and push

git tag vX.Y.Z
git push origin main --tags

5. Create GitHub Release

Generate changelog from commits since previous tag, then publish:

gh release create vX.Y.Z --title "vX.Y.Z" --notes "$(cat <<'EOF'
## Changes

<changelog from git log>
EOF
)"

Group commits by type when there are enough to justify it:

• Features (feat:)
• Fixes (fix:)
• Refactors (refactor:)
• Other (everything else)

For small releases (< 5 commits), a flat list is fine.

Common Mistakes