9.0 KiB
description, aliases
| description | aliases | ||
|---|---|---|---|
| Prepare a new release by updating changelogs, bumping version, and creating release artifacts |
|
changelog-release
Orchestrate the complete release preparation process including changelog finalization, version bumping, and release artifact generation.
Usage
/changelog-release # Interactive release wizard
/changelog-release patch # Patch version bump (x.x.Z)
/changelog-release minor # Minor version bump (x.Y.0)
/changelog-release major # Major version bump (X.0.0)
/changelog-release v2.5.0 # Specific version
/changelog-release --pre-release rc1 # Release candidate
Release Workflow
Phase 1: Pre-Release Checks
- Verify all tests pass
- Check for uncommitted changes
- Validate changelog entries
- Confirm version bump strategy
- Review breaking changes
Phase 2: Version Management
- Calculate new version number
- Update version in all relevant files:
- package.json
- setup.py / pyproject.toml
- VERSION file
- Source code constants
- Update changelog headers
Phase 3: Documentation Finalization
- Move "Unreleased" changes to versioned section
- Generate release summary
- Create migration guide (if breaking changes)
- Generate announcement template
- Update comparison links
Phase 4: Release Artifacts
- Create git commit for release
- Generate git tag
- Create release branch (if applicable)
- Prepare distribution packages
- Generate release notes for platforms
Phase 5: Post-Release Setup
- Create new "Unreleased" section
- Set up next development cycle
- Generate release checklist
- Create follow-up tasks
Agent Orchestration
CRITICAL: You MUST use the Task tool to invoke these agents in sequence for the release workflow.
Agent Invocation Sequence
Invoke agents using the Task tool in this exact order:
1. Project Context Extractor (Claude Haiku)
Use Task tool with:
- subagent_type: "changelog-manager:project-context-extractor"
- description: "Extract project context from documentation"
- prompt: "Analyze CLAUDE.md, README.md, and docs/ to extract project context for user-focused release notes."
Purpose: Reads project documentation to understand how to communicate release information to users.
Output: Project context object with feature catalog, tone guidance, and custom instructions.
2. Git History Analyzer (Claude Sonnet)
Use Task tool with:
- subagent_type: "changelog-manager:git-history-analyzer"
- description: "Analyze unreleased changes"
- prompt: "Extract all unreleased commits (since last version tag), group by PR/feature/semantic similarity, categorize changes, and detect breaking changes to determine appropriate version bump."
Purpose: Analyzes unreleased changes to determine version bump strategy and validate changelog entries.
Output: Structured change data with version bump recommendation (major/minor/patch).
3. GitHub Matcher (Claude Sonnet) - OPTIONAL
Only invoke if GitHub integration enabled.
Use Task tool with:
- subagent_type: "changelog-manager:github-matcher"
- description: "Match unreleased commits to GitHub artifacts"
- prompt: "Enrich unreleased commits with GitHub Issue, PR, Project, and Milestone references for comprehensive release notes."
Purpose: Adds GitHub artifact references to release documentation.
Output: Enriched commit data with GitHub references.
4. Changelog Synthesizer (Claude Sonnet)
Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Finalize release documentation"
- prompt: "Move 'Unreleased' section to versioned release section in CHANGELOG.md, generate user-facing RELEASE_NOTES.md for the new version, create release announcement template, and set up new 'Unreleased' section."
Purpose: Finalizes changelog documentation for the release, generates announcement templates.
Output: Updated CHANGELOG.md, RELEASE_NOTES.md, and release announcement template.
Integration Flow
project-context-extractor (Haiku)
↓
↓ [project_context]
↓
git-history-analyzer (Sonnet)
↓
↓ [git_analysis + version_recommendation]
↓
github-matcher (Sonnet) [OPTIONAL]
↓
↓ [enhanced_analysis]
↓
changelog-synthesizer (Sonnet)
↓
↓ [final_release_docs]
↓
Update version files
Update changelog files
Create git commit
Create git tag
Options
--dry-run: Preview changes without applying--no-tag: Skip git tag creation--no-commit: Skip git commit--pre-release <tag>: Create pre-release (alpha, beta, rc)--skip-tests: Skip test verification--announcement: Generate announcement template
Interactive Example
You: /changelog-release
Claude: 🚀 Release Preparation Wizard
📊 Current Status:
- Current version: v2.3.1
- Unreleased changes: 23 items
- 3 new features (suggests minor bump)
- 12 improvements
- 8 bug fixes
- 0 breaking changes
Suggested version: v2.4.0
What version would you like to release?
1. v2.4.0 (recommended - minor)
2. v2.3.2 (patch)
3. v3.0.0 (major)
4. Custom version
5. Pre-release (rc, beta, alpha)
You: 1
Claude: ✅ Preparing release v2.4.0...
🔍 Running pre-release checks:
- ✅ All tests passing
- ✅ No uncommitted changes
- ✅ Changelog entries valid
- ✅ No unresolved TODOs in code
📝 Updating version files:
- ✅ package.json: 2.3.1 → 2.4.0
- ✅ src/version.py: Updated VERSION constant
- ✅ README.md: Updated version badge
📚 Finalizing documentation:
- ✅ CHANGELOG.md: Moved 23 unreleased items to v2.4.0
- ✅ RELEASE_NOTES.md: Generated user-friendly summary
- ✅ Created release announcement template
Would you like to:
1. Review changes before committing
2. Proceed with release
3. Generate additional artifacts
4. Cancel
You: 1
Claude: 📄 Release Changes Preview:
**CHANGELOG.md excerpt:**
```markdown
## [2.4.0] - 2025-11-13
### Added
- REST API v2 with pagination support (#234)
- WebSocket real-time notifications (#240)
- Docker Compose development environment
RELEASE_NOTES.md excerpt:
## Version 2.4.0 - November 13, 2025
### ✨ What's New
- Real-time notifications keep you updated instantly
- Lightning-fast API with new pagination
- Easier development setup with Docker
Files to be modified:
- CHANGELOG.md
- RELEASE_NOTES.md
- package.json
- src/version.py
Continue with release? (yes/no)
You: yes
Claude: 🎯 Executing release...
✅ Documentation updated ✅ Version files updated ✅ Commit created: "chore(release): Prepare v2.4.0" ✅ Tag created: v2.4.0 ✅ Release branch created: release/v2.4.0
📋 Release Checklist:
□ Push changes: git push origin main --tags
□ Create GitHub release
□ Deploy to production
□ Announce to team/users
□ Monitor for issues
📢 Announcement template saved to: RELEASE_ANNOUNCEMENT.md
🎉 Release v2.4.0 prepared successfully!
## Version Strategies
### Semantic Versioning
MAJOR.MINOR.PATCH
- MAJOR: Breaking changes
- MINOR: New features, backwards compatible
- PATCH: Bug fixes, backwards compatible
### Pre-releases
v2.4.0-rc.1 # Release candidate v2.4.0-beta.2 # Beta version v2.4.0-alpha.3 # Alpha version
### Calendar Versioning
2025.11.13 # Year.Month.Day 2025.11 # Year.Month 25.11.1 # YY.MM.Patch
## Platform Integration
### GitHub Release
```bash
# Generates GitHub-compatible release notes
/changelog-release --platform github
GitLab Release
# Generates GitLab release format
/changelog-release --platform gitlab
npm Publication
# Prepares for npm publish
/changelog-release --platform npm
Configuration
Customize in .changelog.yaml:
release:
# Branches allowed for releases
allowed_branches:
- main
- master
- release/*
# Required checks before release
pre_release_checks:
- tests_pass
- no_uncommitted
- changelog_valid
# Files to update version in
version_files:
- package.json
- setup.py
- src/version.py
- README.md
# Post-release actions
post_release:
- create_github_release
- notify_slack
- trigger_deployment
Automation Hooks
Pre-release Hook
#!/bin/bash
# .changelog-hooks/pre-release.sh
echo "Running pre-release checks..."
npm test
npm run lint
Post-release Hook
#!/bin/bash
# .changelog-hooks/post-release.sh
echo "Triggering deployment..."
curl -X POST https://deploy.example.com/webhook
Best Practices
- Always review generated changes before committing
- Run tests before releasing
- Tag releases for easy rollback
- Document breaking changes thoroughly
- Announce releases to stakeholders
- Monitor post-release for issues
Related Commands
/changelog update- Update with recent changes/version- Manage version numbers/git tag- Create git tags/release-notes- Generate platform-specific notes