Releasing Kata

Guide the release process for Kata's plugin marketplace distribution.

Release Flow Overview

1. Run tests locally
2. Bump version in package.json and plugin.json
3. Update CHANGELOG.md
4. Create release branch and PR
5. Merge PR to main
6. CI automatically: tests → build → create GitHub Release → push to marketplace

Step 1: Pre-Release Verification

Our workflow is PR-driven:

• Development happens on feature branches
• Releases happen on release branches created from main

1a. Ensure you're ready to release

Before creating a release branch, verify:

1. Check current branch: Must be on main (not a feature branch)

   git branch --show-current
   

2. If on a feature branch: The PR must pass CI and be merged first

   # Check PR status
   gh pr status
   
   # Monitor PR CI checks
   gh pr checks --watch 2>&1 | tail -10
   
   # After PR merges, switch to main
   git checkout main && git pull
   

3. Verify working directory is clean:

   git status  # Should show "nothing to commit, working tree clean"
   

1b. Run pre-release checks

Once on main with a clean working directory, verify the codebase is ready:

Stop if tests fail. Fix issues before proceeding.

Step 2: Determine Version Bump

Ask the user what type of release this is:

Type	When to Use	Example
patch	Bug fixes, small improvements	1.0.5 → 1.0.6
minor	New features, backward compatible	1.0.5 → 1.1.0
major	Breaking changes	1.0.5 → 2.0.0

Step 3: Bump Versions

Both files must have matching versions:

1. Read current version from package.json
2. Calculate new version based on bump type
3. Update package.json version field
4. Update .claude-plugin/plugin.json version field

# Get current version
cat package.json | jq -r '.version'

# After updating both files, verify they match
diff <(jq -r '.version' package.json) <(jq -r '.version' .claude-plugin/plugin.json)

Step 4: Update Docs

1: Update CHANGELOG

Add entry to CHANGELOG.md following Keep a Changelog format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New feature descriptions

### Fixed
- Bug fix descriptions

### Changed
- Modification descriptions

Guidelines:

• Use today's date
• Group changes by type (Added, Fixed, Changed, Removed)
• Write user-facing descriptions (what changed, not how)
• Reference issue numbers if applicable

2: Update README (if needed)

If there are significant changes affecting usage, update README.md accordingly.

3: Update Website (if needed)

If there are significant changes affecting documentation, update the website docs accordingly. ~/Users/gannonhall~/dev/kata/kata-site/src

Step 5: Run Tests Again

After version bump, rebuild and test:

npm run build && npm test && npm run test:smoke

Step 6: Create Release PR

# Create release branch
git checkout -b release/vX.Y.Z

# Stage release files
git add package.json .claude-plugin/plugin.json CHANGELOG.md

# Commit with conventional format
git commit -m "chore: bump version to X.Y.Z"

# Push and create PR
git push -u origin release/vX.Y.Z
gh pr create --title "Release vX.Y.Z" --body "## Release vX.Y.Z

### Changes
- [List key changes from CHANGELOG]

### Checklist
- [ ] Version bumped in package.json
- [ ] Version bumped in plugin.json
- [ ] CHANGELOG updated
- [ ] Tests passing"

Step 7: Merge and Monitor CI

# Merge the PR (after review if required)
gh pr merge --merge --delete-branch

# Monitor CI workflows
gh run list --limit 5
gh run watch  # Watch the latest run

CI Pipeline:

1. plugin-release.yml triggers on push to main
2. Detects version change between plugin.json and marketplace
3. Runs tests → Builds → Creates GitHub Release → Pushes to marketplace

Step 8: Verify Release

After CI completes (~2-3 minutes), verify the release.

8a. Verify GitHub Release

# Verify GitHub Release created with tag
gh release view vX.Y.Z

8b. Verify Plugin Marketplace Updated

# Check marketplace version (bypasses CDN cache)
gh api repos/gannonh/kata-marketplace/contents/.claude-plugin/marketplace.json --jq '.content' | base64 -d | jq -r '.plugins[0].version'

# Verify plugin-release workflow ran successfully
gh run list --workflow=plugin-release.yml --limit 3

8c. Manual Plugin Installation Test

This is the one test that can't be fully automated. Test actual plugin installation:

# Create temporary test directory
mkdir -p /tmp/kata-plugin-test && cd /tmp/kata-plugin-test

# Start Claude Code and test interactively
claude

In Claude Code:

/plugin install kata@kata-marketplace
/kata-help
/kata-whats-new

Verify:

• Plugin installs without errors
• /kata-help shows all commands
• /kata-whats-new shows new version changelog
• No path resolution errors

# Cleanup
cd - && rm -rf /tmp/kata-plugin-test

Troubleshooting

See ./release-troubleshooting.md for common issues:

• CI workflow failures
• Plugin marketplace not updating
• Version mismatch errors

Acceptance Criteria

Pre-release:

• package.json version updated
• plugin.json version matches package.json
• CHANGELOG.md has entry for new version
• All tests pass locally (npm test && npm run test:smoke)

Release:

• PR merged to main
• GitHub Release created with correct tag (gh release view vX.Y.Z)

Post-release verification:

• GitHub Release created with tag (gh release view vX.Y.Z)
• Marketplace shows new version (gh api check)
• Manual plugin test passes (/plugin install kata@kata-marketplace + /kata-help)