Releasing Plugin Versions

Critical Distinction

metadata.version ≠ plugin version. These are DIFFERENT things:

Field	What It Tracks	When to Update
`plugins[].version`	Individual plugin version	Every plugin release
`metadata.version`	Marketplace catalog structure	Adding/removing plugins ONLY

Common mistake: Thinking metadata.version should "stay in sync" with plugin versions. It should NOT.

Plugin Version Locations (Update ALL 4)

When releasing a plugin (e.g., swift 1.2.0 → 1.3.0):

plugins/swift/.claude-plugin/plugin.json → "version": "1.3.0"
.claude-plugin/marketplace.json → plugins[].version: "1.3.0"
plugins/swift/README.md → Version section: 1.3.0
README.md (root) → Available Plugins table: 1.3.0

Release Commands

# 1. Stage changes
git add -A

# 2. Commit
git commit -m "Release swift v1.3.0

- Description of changes"

# 3. Tag (format: v1.3.0, NOT swift-v1.3.0)
git tag v1.3.0

# 4. Push
git push && git push origin v1.3.0

# 5. GitHub release
gh release create v1.3.0 --title "v1.3.0" --notes "## Changes

- Change 1
- Change 2

**Full Changelog**: https://github.com/OWNER/REPO/compare/v1.2.0...v1.3.0"

Tag Format

Use v1.3.0, NOT swift-v1.3.0. Check existing tags:

git tag --sort=-v:refname | head -5

When NOT to Update metadata.version

Releasing a new plugin version ❌
Fixing plugin bugs ❌
Adding features to existing plugins ❌
Updating plugin documentation ❌

When TO Update metadata.version

Adding a NEW plugin to the catalog ✓
Removing a plugin from the catalog ✓
Changing marketplace owner/name ✓

releasing-plugin-versions