Initial commit
This commit is contained in:
Zhongwei Li
388
commands/changelog-release.md
Normal file
388
commands/changelog-release.md
Normal file
@@ -0,0 +1,388 @@
|
||||
---
|
||||
description: Prepare a new release by updating changelogs, bumping version, and creating release artifacts
|
||||
aliases: ["cl-release", "release-prep"]
|
||||
---
|
||||
|
||||
# changelog-release
|
||||
|
||||
Orchestrate the complete release preparation process including changelog
|
||||
finalization, version bumping, and release artifact generation.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/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
|
||||
|
||||
```bash
|
||||
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:**
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# Generates GitLab release format
|
||||
/changelog-release --platform gitlab
|
||||
```
|
||||
|
||||
### npm Publication
|
||||
|
||||
```bash
|
||||
# Prepares for npm publish
|
||||
/changelog-release --platform npm
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Customize in `.changelog.yaml`:
|
||||
|
||||
```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
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .changelog-hooks/pre-release.sh
|
||||
echo "Running pre-release checks..."
|
||||
npm test
|
||||
npm run lint
|
||||
```
|
||||
|
||||
### Post-release Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .changelog-hooks/post-release.sh
|
||||
echo "Triggering deployment..."
|
||||
curl -X POST https://deploy.example.com/webhook
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always review** generated changes before committing
|
||||
2. **Run tests** before releasing
|
||||
3. **Tag releases** for easy rollback
|
||||
4. **Document breaking changes** thoroughly
|
||||
5. **Announce releases** to stakeholders
|
||||
6. **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
|
||||
Reference in New Issue
Block a user