refactor: consolidate version bump documentation and remove obsolete files
This commit is contained in:
Alex Newman
@@ -5,94 +5,76 @@ description: Manage semantic version updates for claude-mem project. Handles pat
|
||||
|
||||
# Version Bump Skill
|
||||
|
||||
Manage semantic versioning across the claude-mem project with consistent updates to all version-tracked files.
|
||||
**IMPORTANT:** You must first ultrathink and write detailed release notes before starting the version bump workflow.
|
||||
|
||||
## Quick Reference
|
||||
## Version Types
|
||||
|
||||
- **PATCH** (x.y.Z): Bug fixes only
|
||||
- **MINOR** (x.Y.0): New features, backward compatible
|
||||
- **MAJOR** (X.0.0): Breaking changes
|
||||
|
||||
## Files to Update (ALL THREE)
|
||||
|
||||
**Files requiring updates (ALL THREE):**
|
||||
1. `package.json` (line 3)
|
||||
2. `.claude-plugin/marketplace.json` (line 13)
|
||||
3. `plugin/.claude-plugin/plugin.json` (line 3)
|
||||
|
||||
**Semantic versioning:**
|
||||
- **PATCH** (x.y.Z): Bugfixes only
|
||||
- **MINOR** (x.Y.0): New features, backward compatible
|
||||
- **MAJOR** (X.0.0): Breaking changes
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
**What changed?**
|
||||
- "Fixed a bug" → PATCH (5.3.0 → 5.3.1)
|
||||
- "Added new feature" → MINOR (5.3.0 → 5.4.0)
|
||||
- "Breaking change" → MAJOR (5.3.0 → 6.0.0)
|
||||
|
||||
**If unclear, ASK THE USER explicitly.**
|
||||
|
||||
## Standard Workflow
|
||||
|
||||
See [operations/workflow.md](operations/workflow.md) for detailed step-by-step process.
|
||||
|
||||
**Quick version:**
|
||||
1. Determine version type (PATCH/MINOR/MAJOR)
|
||||
2. Calculate new version from current
|
||||
3. Preview changes to user
|
||||
4. Update ALL THREE files
|
||||
5. Verify consistency
|
||||
6. Build and test
|
||||
7. Commit and create git tag
|
||||
8. Push and create GitHub release
|
||||
9. Generate CHANGELOG.md from releases and commit
|
||||
10. Post Discord notification
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
See [operations/scenarios.md](operations/scenarios.md) for examples:
|
||||
- Bug fix releases
|
||||
- New feature releases
|
||||
- Breaking change releases
|
||||
|
||||
## Critical Rules
|
||||
|
||||
**ALWAYS:**
|
||||
- Update ALL THREE files with matching version numbers
|
||||
- Create git tag with format `vX.Y.Z`
|
||||
- Create GitHub release from the tag
|
||||
- Generate CHANGELOG.md from releases after creating release
|
||||
- Post Discord notification after release
|
||||
- Ask user if version type is unclear
|
||||
|
||||
**NEVER:**
|
||||
- Update only one or two files
|
||||
- Skip the verification step
|
||||
- Forget to create git tag or GitHub release
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before considering the task complete:
|
||||
- [ ] All THREE files have matching version numbers
|
||||
- [ ] `npm run build` succeeds
|
||||
- [ ] Git commit created with all version files
|
||||
- [ ] Git tag created (format: vX.Y.Z)
|
||||
- [ ] Commit and tags pushed to remote
|
||||
- [ ] GitHub release created from the tag
|
||||
- [ ] CHANGELOG.md generated and committed
|
||||
- [ ] Discord notification sent
|
||||
|
||||
## Reference Commands
|
||||
## Workflow
|
||||
|
||||
```bash
|
||||
# View current version
|
||||
grep '"version"' package.json
|
||||
|
||||
# Verify consistency across all version files
|
||||
# 1. Check current version
|
||||
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
|
||||
|
||||
# View git tags
|
||||
git tag -l -n1
|
||||
# 2. Update all 3 files to new version (use Edit tool)
|
||||
|
||||
# Check what will be committed
|
||||
git status
|
||||
git diff package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
|
||||
# 3. Verify consistency
|
||||
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
|
||||
|
||||
# 4. Build
|
||||
npm run build
|
||||
|
||||
# 5. Commit version files
|
||||
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
|
||||
git commit -m "chore: bump version to X.Y.Z"
|
||||
|
||||
# 6. Create tag
|
||||
git tag -a vX.Y.Z -m "Version X.Y.Z"
|
||||
|
||||
# 7. Push
|
||||
git push origin main && git push origin vX.Y.Z
|
||||
|
||||
# 8. Create GitHub release (use your detailed release notes here)
|
||||
gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES_HERE"
|
||||
|
||||
# 9. Generate CHANGELOG.md from releases
|
||||
gh api repos/thedotmack/claude-mem/releases --paginate | node -e "
|
||||
const releases = JSON.parse(require('fs').readFileSync(0, 'utf8'));
|
||||
const lines = ['# Changelog', '', 'All notable changes to claude-mem.', ''];
|
||||
releases.slice(0, 50).forEach(r => {
|
||||
const date = r.published_at.split('T')[0];
|
||||
lines.push('## [' + r.tag_name + '] - ' + date);
|
||||
lines.push('');
|
||||
if (r.body) lines.push(r.body.trim());
|
||||
lines.push('');
|
||||
});
|
||||
console.log(lines.join('\n'));
|
||||
" > CHANGELOG.md
|
||||
|
||||
# 10. Commit CHANGELOG
|
||||
git add CHANGELOG.md
|
||||
git commit -m "docs: update CHANGELOG.md for vX.Y.Z"
|
||||
git push origin main
|
||||
|
||||
# 11. Discord notification
|
||||
npm run discord:notify vX.Y.Z
|
||||
```
|
||||
|
||||
For more commands, see [operations/reference.md](operations/reference.md).
|
||||
## Checklist
|
||||
|
||||
- [ ] Ultrathink + write detailed release notes
|
||||
- [ ] All 3 files have matching version
|
||||
- [ ] `npm run build` succeeds
|
||||
- [ ] Git tag created (vX.Y.Z format)
|
||||
- [ ] GitHub release created with detailed notes
|
||||
- [ ] CHANGELOG.md updated
|
||||
- [ ] Discord notification sent (if webhook configured)
|
||||
|
||||
@@ -1,265 +0,0 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Build plugin
|
||||
npm run build
|
||||
|
||||
# Sync to marketplace
|
||||
npm run sync-marketplace
|
||||
|
||||
# Run tests (if available)
|
||||
npm test
|
||||
```
|
||||
|
||||
### Commit and Tag
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Delete GitHub release
|
||||
gh release delete vX.Y.Z
|
||||
|
||||
# Confirm deletion
|
||||
gh release delete vX.Y.Z --yes
|
||||
```
|
||||
|
||||
### Revert Commit
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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"
|
||||
```
|
||||
@@ -1,218 +0,0 @@
|
||||
# Common Version Bump Scenarios
|
||||
|
||||
Real-world examples of version bumps with decision rationale.
|
||||
|
||||
## Scenario 1: Bug Fix After Testing
|
||||
|
||||
**User request:**
|
||||
> "Fixed the memory leak in the search function"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: Bug fix
|
||||
- Breaking changes: No
|
||||
- New features: No
|
||||
- **Decision: PATCH**
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Current: 4.2.8
|
||||
New: 4.2.9 (PATCH)
|
||||
|
||||
Steps:
|
||||
1. Update all three files to 4.2.9
|
||||
2. npm run build
|
||||
3. git commit -m "Release v4.2.9: Fixed memory leak in search"
|
||||
4. git tag v4.2.9 -m "Release v4.2.9: Fixed memory leak in search"
|
||||
5. git push && git push --tags
|
||||
6. gh release create v4.2.9 --title "v4.2.9" --notes "Fixed memory leak in search function"
|
||||
```
|
||||
|
||||
## Scenario 2: New Feature Added
|
||||
|
||||
**User request:**
|
||||
> "Added web search MCP integration"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: New feature (MCP integration)
|
||||
- Breaking changes: No
|
||||
- Backward compatible: Yes
|
||||
- **Decision: MINOR**
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Current: 4.2.8
|
||||
New: 4.3.0 (MINOR - reset patch to 0)
|
||||
|
||||
Steps:
|
||||
1. Update all three files to 4.3.0
|
||||
2. npm run build
|
||||
3. git commit -m "Release v4.3.0: Added web search MCP integration"
|
||||
4. git tag v4.3.0 -m "Release v4.3.0: Added web search MCP integration"
|
||||
5. git push && git push --tags
|
||||
6. gh release create v4.3.0 --title "v4.3.0" --generate-notes
|
||||
```
|
||||
|
||||
## Scenario 3: Database Schema Redesign
|
||||
|
||||
**User request:**
|
||||
> "Rewrote storage layer, old data needs migration"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: Storage layer rewrite
|
||||
- Breaking changes: Yes (requires migration)
|
||||
- Backward compatible: No
|
||||
- **Decision: MAJOR**
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Current: 4.2.8
|
||||
New: 5.0.0 (MAJOR - reset minor and patch to 0)
|
||||
|
||||
Steps:
|
||||
1. Update all three files to 5.0.0
|
||||
2. npm run build
|
||||
3. git commit -m "Release v5.0.0: Storage layer redesign with migration required"
|
||||
4. git tag v5.0.0 -m "Release v5.0.0: Storage layer redesign"
|
||||
5. git push && git push --tags
|
||||
6. gh release create v5.0.0 --title "v5.0.0" --notes "⚠️ Breaking change: Storage layer redesigned. Migration required."
|
||||
```
|
||||
|
||||
## Scenario 4: Multiple Small Bug Fixes
|
||||
|
||||
**User request:**
|
||||
> "Fixed three bugs: observer crash, viewer pagination, and date formatting"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: Multiple bug fixes
|
||||
- Breaking changes: No
|
||||
- New features: No
|
||||
- **Decision: PATCH** (one patch covers all fixes)
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Current: 4.2.8
|
||||
New: 4.2.9 (PATCH)
|
||||
|
||||
Steps:
|
||||
1. Update all three files to 4.2.9
|
||||
2. npm run build
|
||||
3. git commit -m "Release v4.2.9: Multiple bug fixes
|
||||
|
||||
- Fixed observer crash on empty content
|
||||
- Fixed viewer pagination edge case
|
||||
- Fixed date formatting in timeline"
|
||||
4. git tag v4.2.9 -m "Release v4.2.9: Multiple bug fixes"
|
||||
5. git push && git push --tags
|
||||
6. gh release create v4.2.9 --title "v4.2.9" --generate-notes
|
||||
```
|
||||
|
||||
## Scenario 5: Feature + Bug Fix
|
||||
|
||||
**User request:**
|
||||
> "Added dark mode support and fixed the viewer crash bug"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: New feature + bug fix
|
||||
- Breaking changes: No
|
||||
- **Decision: MINOR** (feature trumps bug fix)
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Current: 5.1.0
|
||||
New: 5.2.0 (MINOR)
|
||||
|
||||
Steps:
|
||||
1. Update all three files to 5.2.0
|
||||
2. npm run build
|
||||
3. git commit -m "Release v5.2.0: Dark mode support + bug fixes
|
||||
|
||||
Features:
|
||||
- Added dark mode toggle to viewer UI
|
||||
|
||||
Bug fixes:
|
||||
- Fixed viewer crash on empty database"
|
||||
4. git tag v5.2.0 -m "Release v5.2.0: Dark mode support"
|
||||
5. git push && git push --tags
|
||||
6. gh release create v5.2.0 --title "v5.2.0" --generate-notes
|
||||
```
|
||||
|
||||
## Scenario 6: Documentation Only
|
||||
|
||||
**User request:**
|
||||
> "Updated README with new installation instructions"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: Documentation only
|
||||
- Breaking changes: No
|
||||
- Code changes: No
|
||||
- **Decision: PATCH** (or skip version bump if no code changes)
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Option 1: PATCH (if you want to tag doc improvements)
|
||||
Current: 4.2.8
|
||||
New: 4.2.9
|
||||
|
||||
Option 2: No version bump (documentation-only changes don't require versioning)
|
||||
Just commit without bumping version
|
||||
```
|
||||
|
||||
**Recommendation:** Skip version bump for documentation-only changes unless it's a significant documentation overhaul.
|
||||
|
||||
## Scenario 7: Configuration Change
|
||||
|
||||
**User request:**
|
||||
> "Changed default observation count from 50 to 30"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: Default configuration
|
||||
- Breaking changes: Yes (behavior changes)
|
||||
- Users might notice different context size
|
||||
- **Decision: MINOR or MAJOR** (ask user)
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Ask user:
|
||||
"This changes default behavior (context size). Users will see different results.
|
||||
Is this:
|
||||
- MINOR (acceptable behavior change): 4.2.8 → 4.3.0
|
||||
- MAJOR (breaking change): 4.2.8 → 5.0.0
|
||||
|
||||
Which should I use?"
|
||||
```
|
||||
|
||||
## Scenario 8: Dependency Update
|
||||
|
||||
**User request:**
|
||||
> "Updated Claude SDK from 1.2.0 to 1.3.0"
|
||||
|
||||
**Analysis:**
|
||||
- What changed: Dependency version
|
||||
- Breaking changes: Depends on SDK changes
|
||||
- **Decision: Ask user or check SDK changelog**
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
1. Check SDK changelog for breaking changes
|
||||
2. If SDK has breaking changes → MAJOR
|
||||
3. If SDK adds features → MINOR
|
||||
4. If SDK only fixes bugs → PATCH
|
||||
|
||||
Typical: PATCH (unless SDK breaks compatibility)
|
||||
```
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Is there a breaking change?
|
||||
├─ Yes → MAJOR (X.0.0)
|
||||
└─ No
|
||||
├─ Is there a new feature?
|
||||
│ ├─ Yes → MINOR (x.Y.0)
|
||||
│ └─ No
|
||||
│ ├─ Is there a bug fix?
|
||||
│ │ ├─ Yes → PATCH (x.y.Z)
|
||||
│ │ └─ No → Don't bump version (docs only, etc.)
|
||||
│ └─ Configuration change? → Ask user (MINOR or MAJOR)
|
||||
└─ Multiple changes? → Use highest level (MAJOR > MINOR > PATCH)
|
||||
```
|
||||
@@ -1,249 +0,0 @@
|
||||
# Detailed Version Bump Workflow
|
||||
|
||||
Step-by-step process for bumping versions in the claude-mem project.
|
||||
|
||||
## Step 1: Analyze Changes
|
||||
|
||||
First, understand what changed:
|
||||
|
||||
```bash
|
||||
# View recent commits
|
||||
git log --oneline -5
|
||||
|
||||
# See what changed in last commit
|
||||
git diff HEAD~1
|
||||
|
||||
# Or see all changes since last tag
|
||||
LAST_TAG=$(git describe --tags --abbrev=0)
|
||||
git log $LAST_TAG..HEAD --oneline
|
||||
git diff $LAST_TAG..HEAD
|
||||
```
|
||||
|
||||
## Step 2: Determine Version Type
|
||||
|
||||
Ask yourself:
|
||||
- **Breaking changes?** → MAJOR
|
||||
- **New features?** → MINOR
|
||||
- **Bugfixes only?** → PATCH
|
||||
|
||||
**If unclear, ASK THE USER explicitly.**
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Change Type | Version Bump | Example |
|
||||
|------------|--------------|---------|
|
||||
| Bug fix | PATCH | 4.2.8 → 4.2.9 |
|
||||
| New feature (backward compatible) | MINOR | 4.2.8 → 4.3.0 |
|
||||
| Breaking change | MAJOR | 4.2.8 → 5.0.0 |
|
||||
| Multiple features | MINOR | 4.2.8 → 4.3.0 |
|
||||
| Feature + breaking change | MAJOR | 4.2.8 → 5.0.0 |
|
||||
|
||||
## Step 3: Calculate New Version
|
||||
|
||||
From current version in `package.json`:
|
||||
|
||||
```bash
|
||||
grep '"version"' package.json
|
||||
```
|
||||
|
||||
Apply semantic versioning rules:
|
||||
- **Patch:** increment Z (4.2.8 → 4.2.9)
|
||||
- **Minor:** increment Y, reset Z (4.2.8 → 4.3.0)
|
||||
- **Major:** increment X, reset Y and Z (4.2.8 → 5.0.0)
|
||||
|
||||
## Step 4: Preview Changes
|
||||
|
||||
**BEFORE making changes, show the user:**
|
||||
|
||||
```
|
||||
Current version: 4.2.8
|
||||
New version: 4.2.9 (PATCH)
|
||||
Reason: Fixed database query bug
|
||||
|
||||
Files to update:
|
||||
- package.json: "version": "4.2.9"
|
||||
- marketplace.json: "version": "4.2.9"
|
||||
- plugin.json: "version": "4.2.9"
|
||||
- Git tag: v4.2.9
|
||||
|
||||
Proceed? (yes/no)
|
||||
```
|
||||
|
||||
Wait for user confirmation before proceeding.
|
||||
|
||||
## Step 5: Update Files
|
||||
|
||||
### Update package.json
|
||||
|
||||
File: `package.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "claude-mem",
|
||||
"version": "4.2.9",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Update line 3 with new version.
|
||||
|
||||
### Update marketplace.json
|
||||
|
||||
File: `.claude-plugin/marketplace.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "claude-mem",
|
||||
"version": "4.2.9",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Update line 13 with new version.
|
||||
|
||||
### Update plugin.json
|
||||
|
||||
File: `plugin/.claude-plugin/plugin.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "claude-mem",
|
||||
"version": "4.2.9",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Update line 3 with new version.
|
||||
|
||||
## Step 6: Verify Consistency
|
||||
|
||||
```bash
|
||||
# Check all versions match
|
||||
grep -n '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
|
||||
|
||||
# Should show same version in all three files:
|
||||
# package.json:3: "version": "4.2.9",
|
||||
# .claude-plugin/marketplace.json:13: "version": "4.2.9",
|
||||
# plugin/.claude-plugin/plugin.json:3: "version": "4.2.9",
|
||||
```
|
||||
|
||||
All three must match exactly.
|
||||
|
||||
## Step 7: Test
|
||||
|
||||
```bash
|
||||
# Verify the plugin loads correctly
|
||||
npm run build
|
||||
```
|
||||
|
||||
Build must succeed before proceeding.
|
||||
|
||||
## Step 8: Commit and Tag
|
||||
|
||||
```bash
|
||||
# Stage all version files
|
||||
git add package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json plugin/scripts/
|
||||
|
||||
# Commit with descriptive message
|
||||
git commit -m "Release vX.Y.Z: [Brief description]
|
||||
|
||||
[Optional detailed description]
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
# Create annotated git tag
|
||||
git tag vX.Y.Z -m "Release vX.Y.Z: [Brief description]"
|
||||
|
||||
# Push commit and tags
|
||||
git push && git push --tags
|
||||
```
|
||||
|
||||
Replace `X.Y.Z` with actual version (e.g., `4.2.9`).
|
||||
|
||||
## Step 9: Create GitHub Release
|
||||
|
||||
```bash
|
||||
# Create GitHub release from the tag
|
||||
gh release create vX.Y.Z --title "vX.Y.Z" --notes "[Brief release notes]"
|
||||
|
||||
# Or generate notes automatically from commits
|
||||
gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
|
||||
```
|
||||
|
||||
**IMPORTANT:** Always create the GitHub release immediately after pushing the tag. This makes the release discoverable to users and triggers any automated workflows.
|
||||
|
||||
## Step 10: Generate CHANGELOG
|
||||
|
||||
After creating the GitHub release, regenerate CHANGELOG.md from all releases:
|
||||
|
||||
```bash
|
||||
# Generate CHANGELOG.md from all GitHub releases
|
||||
npm run changelog:generate
|
||||
|
||||
# Review the generated changelog
|
||||
git diff CHANGELOG.md
|
||||
|
||||
# Commit and push the updated changelog
|
||||
git add CHANGELOG.md
|
||||
git commit -m "Update CHANGELOG.md for vX.Y.Z release"
|
||||
git push
|
||||
```
|
||||
|
||||
**Why this step:**
|
||||
- CHANGELOG.md is auto-generated from GitHub releases
|
||||
- Keeps the changelog in sync with release notes
|
||||
- No manual editing required
|
||||
- Single source of truth: GitHub releases
|
||||
|
||||
## Step 11: Discord Notification
|
||||
|
||||
Post release announcement to the Discord updates channel:
|
||||
|
||||
```bash
|
||||
# Send Discord notification with release details
|
||||
npm run discord:notify vX.Y.Z
|
||||
```
|
||||
|
||||
This fetches the release notes from GitHub and posts a formatted embed to the Discord updates channel configured in `.env`.
|
||||
|
||||
## Verification
|
||||
|
||||
After completing all steps, verify:
|
||||
|
||||
```bash
|
||||
# Check git tag created
|
||||
git tag -l | grep vX.Y.Z
|
||||
|
||||
# Check remote has tag
|
||||
git ls-remote --tags origin | grep vX.Y.Z
|
||||
|
||||
# Check GitHub release exists
|
||||
gh release view vX.Y.Z
|
||||
|
||||
# Verify versions match
|
||||
grep '"version"' package.json .claude-plugin/marketplace.json plugin/.claude-plugin/plugin.json
|
||||
```
|
||||
|
||||
All checks should pass.
|
||||
|
||||
## Rollback (If Needed)
|
||||
|
||||
If you made a mistake:
|
||||
|
||||
```bash
|
||||
# Delete local tag
|
||||
git tag -d vX.Y.Z
|
||||
|
||||
# Delete remote tag (if already pushed)
|
||||
git push origin :refs/tags/vX.Y.Z
|
||||
|
||||
# Delete GitHub release (if created)
|
||||
gh release delete vX.Y.Z
|
||||
|
||||
# Revert commits if needed
|
||||
git revert HEAD
|
||||
```
|
||||
|
||||
Then restart the workflow with correct version.
|
||||
Reference in New Issue
Block a user