claude-mem/.claude/skills/version-bump/operations/reference.md

Version Bump Reference

Quick reference for version bump commands and file locations.

File Locations

Version-Tracked Files (ALL THREE)

1. package.json

   • Path: package.json
   • Line: 3
   • Format: "version": "X.Y.Z",

2. marketplace.json

   • Path: .claude-plugin/marketplace.json
   • Line: 13
   • Format: "version": "X.Y.Z",

3. plugin.json

   • Path: plugin/.claude-plugin/plugin.json
   • Line: 3
   • Format: "version": "X.Y.Z",

Essential Commands

View Current Version

# From package.json
grep '"version"' package.json

# Extract just the version number
grep '"version"' package.json | head -1 | sed 's/.*"version": "\(.*\)".*/\1/'

# From all version files
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json

Verify Version Consistency

# Check all JSON files match
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json

# Should output identical version in all three:
# package.json:3:  "version": "5.3.0",
# .claude-plugin/marketplace.json:13:  "version": "5.3.0",
# plugin/.claude-plugin/plugin.json:3:  "version": "5.3.0",

Git Commands

# View recent commits
git log --oneline -5

# View changes since last tag
LAST_TAG=$(git describe --tags --abbrev=0)
git log $LAST_TAG..HEAD --oneline
git diff $LAST_TAG..HEAD

# List all tags
git tag -l

# View tag details
git show vX.Y.Z

# List tags with messages
git tag -l -n1

Build and Test

# Build plugin
npm run build

# Sync to marketplace
npm run sync-marketplace

# Run tests (if available)
npm test

Commit and Tag

# Stage version files
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/

# Commit
git commit -m "Release vX.Y.Z: [Description]"

# Create tag
git tag vX.Y.Z -m "Release vX.Y.Z: [Description]"

# Push
git push && git push --tags

GitHub Release

# Create release
gh release create vX.Y.Z --title "vX.Y.Z" --notes "[Release notes]"

# Create with auto-generated notes
gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes

# View release
gh release view vX.Y.Z

# List all releases
gh release list

# Delete release (if needed)
gh release delete vX.Y.Z

Semantic Versioning Rules

Version Format: MAJOR.MINOR.PATCH

MAJOR (X.0.0):

• Breaking changes
• Incompatible API changes
• Schema changes requiring migration
• Removes features

MINOR (x.Y.0):

• New features (backward compatible)
• New functionality
• Deprecations (but not removals)
• Resets PATCH to 0

PATCH (x.y.Z):

• Bug fixes
• Performance improvements
• Documentation fixes
• No new features

Incrementing Rules

PATCH: 5.3.2 → 5.3.3
MINOR: 5.3.2 → 5.4.0 (resets patch)
MAJOR: 5.3.2 → 6.0.0 (resets minor and patch)

Common Patterns

Bug Fix Release

# Example: 5.3.0 → 5.3.1
# 1. Update all three files to 5.3.1
# 2. Build and test
npm run build
# 3. Commit and tag
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
git commit -m "Release v5.3.1: Fixed observer crash"
git tag v5.3.1 -m "Release v5.3.1: Fixed observer crash"
git push && git push --tags
# 4. Create release
gh release create v5.3.1 --title "v5.3.1" --notes "Fixed observer crash on empty content"

Feature Release

# Example: 5.3.0 → 5.4.0
# 1. Update all three files to 5.4.0
# 2. Build and test
npm run build
# 3. Commit and tag
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
git commit -m "Release v5.4.0: Added dark mode support"
git tag v5.4.0 -m "Release v5.4.0: Added dark mode support"
git push && git push --tags
# 4. Create release
gh release create v5.4.0 --title "v5.4.0" --generate-notes

Breaking Change Release

# Example: 5.3.0 → 6.0.0
# 1. Update all three files to 6.0.0
# 2. Build and test
npm run build
# 3. Commit and tag
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
git commit -m "Release v6.0.0: Storage layer redesign"
git tag v6.0.0 -m "Release v6.0.0: Storage layer redesign"
git push && git push --tags
# 4. Create release with warning
gh release create v6.0.0 --title "v6.0.0" --notes "⚠️ Breaking change: Storage layer redesigned. Migration required."

Rollback Commands

Delete Tag

# Delete local tag
git tag -d vX.Y.Z

# Delete remote tag
git push origin :refs/tags/vX.Y.Z
# Or: git push --delete origin vX.Y.Z

Delete Release

# Delete GitHub release
gh release delete vX.Y.Z

# Confirm deletion
gh release delete vX.Y.Z --yes

Revert Commit

# Revert last commit (creates new commit)
git revert HEAD

# Reset to previous commit (destructive)
git reset --hard HEAD~1
git push --force  # Dangerous! Only if not shared

Error Prevention

Pre-commit Checks

# Check all versions match before committing
V1=$(grep '"version"' package.json | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
V2=$(grep '"version"' .claude-plugin/marketplace.json | sed 's/.*"\([^"]*\)".*/\1/')
V3=$(grep '"version"' plugin/.claude-plugin/plugin.json | head -1 | sed 's/.*"\([^"]*\)".*/\1/')

if [ "$V1" = "$V2" ] && [ "$V2" = "$V3" ]; then
  echo "✓ All versions match: $V1"
else
  echo "✗ Version mismatch!"
  echo "  package.json: $V1"
  echo "  marketplace.json: $V2"
  echo "  plugin.json: $V3"
fi

Pre-push Checks

# Check tag exists
git tag -l | grep vX.Y.Z || echo "Warning: Tag not created"

# Check build succeeds
npm run build || echo "Error: Build failed"

# Check no uncommitted changes
git status --porcelain | grep -q . && echo "Warning: Uncommitted changes"