release

# Plugin Release Process Complete guide for releasing new versions of plugins in the MAG Claude Plugins marketplace. ## Critical Understanding Claude Code plugin discovery works through **TWO** configuration files that **MUST BOTH BE UPDATED**: 1. **`plugins/{plugin-name}/plugin.json`** - The plugin's own version metadata 2. **`.claude-plugin/marketplace.json`** - The marketplace catalog (what users see when browsing) **Why both?** - `plugin.json` - Defines the plugin itself (agents, commands, version) - `marketplace.json` - The "catalog" that Claude Code reads for plugin discovery - Users run `/plugin marketplace update` which reads `marketplace.json` - **If you only update `plugin.json`, users won't see the new version!** --- ## Release Checklist ### Step 1: Update Plugin Files - [ ] `plugins/{plugin-name}/plugin.json` - Update `version` field - [ ] `plugins/{plugin-name}/agents/*.md` - Add new agents (if any) - [ ] `plugins/{plugin-name}/commands/*.md` - Update commands (if any) - [ ] `plugins/{plugin-name}/skills/*/SKILL.md` - Add new skills (if any) ### Step 2: Update Documentation - [ ] `CHANGELOG.md` - Add new version entry at the top - [ ] `RELEASES.md` - Add detailed release notes at the top - [ ] `CLAUDE.md` - Update ALL version references (6+ locations) ### Step 3: ⚠️ **CRITICAL** - Update Marketplace Catalog **File:** `.claude-plugin/marketplace.json` Update TWO fields: 1. **Marketplace metadata version** (line ~10): ```json "metadata": { "version": "3.3.0" // ← Update this } ``` 2. **Specific plugin version** (in plugins array): ```json "plugins": [ { "name": "frontend", "version": "3.3.0", // ← Update this (CRITICAL!) "description": "..." // ← Update if description changed } ] ``` ### Step 4: Commit and Tag ```bash # Commit all changes git add -A git commit -m "feat({plugin}): v{X.Y.Z} - {Feature summary}" # Create tag (format: plugins/{plugin-name}/v{X.Y.Z}) git tag -a plugins/{plugin}/v{X.Y.Z} -m "..." # Push git push origin main git push origin plugins/{plugin}/v{X.Y.Z} ``` ### Step 5: Verify ```bash /plugin marketplace update mag-claude-plugins # Should show new version ✅ ``` --- ## Common Mistakes ### ❌ #1: Forgot to update marketplace.json **Symptom:** Users still see old version after `/plugin marketplace update` **Fix:** ```bash # Update .claude-plugin/marketplace.json vim .claude-plugin/marketplace.json # Update plugins[].version field git add .claude-plugin/marketplace.json git commit -m "fix(marketplace): Update {plugin} version to v{X.Y.Z}" git push origin main ``` ### ❌ #2: Wrong git tag format **Wrong:** `frontend-v3.3.0`, `v3.3.0`, `frontend/v3.3.0` **Correct:** `plugins/frontend/v3.3.0` ✅ ### ❌ #3: Inconsistent versions **Problem:** plugin.json says v3.3.0 but marketplace.json says v3.2.0 **Prevention:** Use checklist, search for old version: `grep -r "3.2.0" .` --- ## Version Numbering **MAJOR (X.0.0):** Breaking changes (removed agents, changed behavior) **MINOR (x.Y.0):** New features (new agents/commands, backward compatible) **PATCH (x.y.Z):** Bug fixes (no new features, backward compatible) --- ## Quick Reference **Minimal checklist:** 1. ✅ Update `plugins/{plugin}/plugin.json` version 2. ✅ Update `.claude-plugin/marketplace.json` plugin version ⚠️ **CRITICAL** 3. ✅ Update `CHANGELOG.md`, `RELEASES.md`, `CLAUDE.md` 4. ✅ Commit: `git commit -m "feat({plugin}): v{X.Y.Z} - {summary}"` 5. ✅ Tag: `git tag -a plugins/{plugin}/v{X.Y.Z} -m "..."` 6. ✅ Push: `git push origin main && git push origin plugins/{plugin}/v{X.Y.Z}` 7. ✅ Verify: `/plugin marketplace update` shows new version --- ## Example Release ```bash # 1. Update versions vim plugins/frontend/plugin.json # version: "3.3.0" vim .claude-plugin/marketplace.json # plugins[0].version: "3.3.0" ← DON'T FORGET! vim CHANGELOG.md RELEASES.md CLAUDE.md # 2. Commit git add -A git commit -m "feat(frontend): v3.3.0 - Multi-Model Plan Review" # 3. Tag git tag -a plugins/frontend/v3.3.0 -m "Frontend Plugin v3.3.0" # 4. Push git push origin main git push origin plugins/frontend/v3.3.0 # 5. Verify /plugin marketplace update mag-claude-plugins # Output: frontend v3.3.0 ✅ ``` --- ## Troubleshooting **Q: Users still see old version** **A:** Check `.claude-plugin/marketplace.json` - version must match `plugin.json` **Q: Tag already exists** **A:** `git tag -d {tag}` then `git push origin :{tag}` then recreate **Q: How to test locally?** **A:** `/plugin marketplace add /path/to/claude-code` --- **Related:** [RELEASE_PROCESS.md](../../RELEASE_PROCESS.md) - Full detailed documentation **Last Updated:** November 13, 2025