zhongwei/gh-mtr-marketplace-changelog-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:41:36 +08:00
commit ec5c049ea6
13 changed files with 6235 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

717
commands/changelog-init.md Normal file
View File

@@ -0,0 +1,717 @@
---
description: Initialize CHANGELOG.md and RELEASE_NOTES.md for a new project or retroactively from git history
aliases: ["cl-init"]
---
# changelog-init
Initialize changelog documentation for a project by analyzing entire git history
and generating both developer and user-facing documentation files.
## Usage
```bash
/changelog-init # Interactive initialization
/changelog-init --from-beginning # Analyze entire git history
/changelog-init --from-tag v1.0.0 # Start from specific version
/changelog-init --empty # Create empty template files
# Historical Replay Mode (NEW)
/changelog-init --replay # Interactive period-based replay
/changelog-init --replay --period monthly # Monthly period grouping
/changelog-init --replay --period weekly # Weekly period grouping
/changelog-init --replay --period by-release # Group by releases
/changelog-init --replay --period auto # Auto-detect best period
```
## Workflow
### Step 1: Project Analysis
- Detects existing version files (package.json, setup.py, etc.)
- Identifies versioning scheme in use
- Analyzes git tag patterns
- Detects commit message conventions
### Step 2: History Processing
- Extracts all commits from starting point
- Groups by releases (if tags exist)
- Categorizes changes
- Identifies key milestones
### Step 3: File Generation
- Creates CHANGELOG.md with complete history
- Creates RELEASE_NOTES.md with major highlights
- Generates .changelog.yaml configuration
- Sets up .changelog-metadata.json for tracking
## Replay Workflow (Historical Period-Based Generation)
The `--replay` mode generates changelogs by "replaying" history through time periods (daily/weekly/monthly/by-release), creating changelog entries as if they were updated in real-time during development.
### Phase 1: Period Detection
**Agent: period-detector (Claude Haiku)**
```
🔍 Analyzing repository structure...
Repository: user/awesome-project
First commit: 2023-03-15 (619 days ago)
Total commits: 523
Contributors: 24
Git tags: 12 releases detected
Auto-detecting optimal period strategy...
✅ Recommended: weekly (21.4 commits/week average)
Period options:
1. Weekly (74 periods, ~7 commits/period)
2. Monthly (20 periods, ~26 commits/period)
3. By-Release (12 periods, ~44 commits/period)
4. Auto (use recommended: weekly)
Select period strategy [1-4] or press Enter for auto: _
```
**Detection Logic:**
- Analyzes commit frequency and distribution
- Detects existing release tags
- Calculates project age and activity patterns
- Provides smart recommendations with rationale
### Phase 2: Boundary Calculation
**Agent: period-detector (Claude Haiku)**
```
📅 Calculating period boundaries...
Strategy: Weekly (Monday-Sunday)
Total periods: 74
Empty periods (will be skipped): 8
Merge-only periods (will be skipped): 3
Active periods to analyze: 63
Period boundaries:
- Week 1: 2023-03-13 to 2023-03-19 (15 commits)
- Week 2: 2023-03-20 to 2023-03-26 (22 commits)
- Week 3: 2023-03-27 to 2023-04-02 (18 commits)
...
- Week 74: 2025-11-10 to 2025-11-16 (8 commits) [Unreleased]
First period note: Week 1 has 287 commits (initial development)
→ Will use summary mode for clarity
Continue with analysis? [Y/n]: _
```
**Boundary Features:**
- Calendar-aligned periods (weeks start Monday, months are calendar months)
- Automatic skip of empty periods
- Automatic skip of merge-only periods
- First-period summarization for large initial development
- Partial final period handling (→ [Unreleased])
### Phase 3: Parallel Period Analysis
**Agent: period-coordinator (Claude Sonnet)**
```
⚙️ Orchestrating multi-period analysis...
Execution plan:
- Total periods: 63
- Concurrent workers: 3
- Estimated time: ~4 minutes
- Cache enabled: Yes
Batch 1/21: Analyzing periods 1-3 in parallel...
✅ Week 1 (2023-03-13): 287 commits → Summarized
✅ Week 2 (2023-03-20): 22 commits → 18 changes categorized
✅ Week 3 (2023-03-27): 18 commits → 15 changes categorized
Batch 2/21: Analyzing periods 4-6 in parallel...
✅ Week 4 (2023-04-03): 25 commits → 20 changes categorized
⚠️ Week 5 (2023-04-10): Analysis timeout, retrying...
✅ Week 5 (2023-04-10): 31 commits → 28 changes categorized
✅ Week 6 (2023-04-17): 19 commits → 16 changes categorized
[Progress: 9/63 periods complete - 14% - ETA 3m 42s]
...
```
**Per-Period Analysis:**
Each period invokes:
1. **git-history-analyzer** (Sonnet): Extract and group commits for period
2. **commit-analyst** (Haiku): Batch-analyze unclear commits (invoked automatically by git-history-analyzer)
3. Caching: Results cached per period for instant regeneration
### Phase 4: Changelog Synthesis
**Agent: changelog-synthesizer (Claude Sonnet)**
```
📝 Generating hybrid-format changelog...
Format: Hybrid (version releases with period subsections)
Structure:
- [Unreleased] section: 2 active periods
- Released versions: 12 versions across 61 periods
- Total entries: 412 changes categorized
Generating CHANGELOG.md...
✅ 63 period sections created
✅ 12 version sections created
✅ Navigation TOC added (74 periods)
✅ 412 changes formatted
Generating RELEASE_NOTES.md...
✅ Period-aware user-facing notes created
✅ Adapted tone for end-users
✅ Highlighted major features per period
```
**Output Format:**
- **CHANGELOG.md**: Hybrid format with version sections containing period subsections
- **RELEASE_NOTES.md**: User-friendly with period-based highlights
- **Navigation**: Table of contents for changelogs >10 periods
### Phase 5: Verification and Commit
```
✅ Changelog generation complete!
Files created:
- CHANGELOG.md (1,847 lines, 63 period sections)
- RELEASE_NOTES.md (423 lines, user-friendly format)
- .changelog.yaml (configuration persisted)
- .changelog-cache/ (63 period analyses cached)
Preview of CHANGELOG.md:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Changelog
## [Unreleased]
### Week of November 11, 2025
#### Added
- Real-time notification system (#256)
### Week of November 4, 2025
#### Added
- Advanced search filters (#252)
## [2.1.0] - 2024-10-27
### Week of October 21, 2024
#### Added
- REST API v2 with pagination (#234)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Actions:
1. Review generated files? [Y/n]
2. Commit to git? [Y/n]
3. Create version tag? [y/N]
```
## Agent Orchestration
**CRITICAL**: You MUST use the Task tool to invoke these agents in the correct sequence.
### Standard Mode Agent Sequence
For standard `/changelog-init` (non-replay):
#### 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."
```
#### 2. Git History Analyzer (Claude Sonnet)
```
Use Task tool with:
- subagent_type: "changelog-manager:git-history-analyzer"
- description: "Analyze entire git history"
- prompt: "Extract all commits from beginning (or specified tag), group by releases/PRs/features, categorize changes, and detect breaking changes."
```
#### 3. GitHub Matcher (Claude Sonnet) - OPTIONAL
```
Only invoke if GitHub integration enabled.
Use Task tool with:
- subagent_type: "changelog-manager:github-matcher"
- description: "Match commits to GitHub artifacts"
- prompt: "Enrich all historical commits with GitHub references."
```
#### 4. Changelog Synthesizer (Claude Sonnet)
```
Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Generate initial changelog files"
- prompt: "Generate complete CHANGELOG.md and RELEASE_NOTES.md from entire project history using project context for user focus."
```
### Replay Mode Agent Sequence
For `/changelog-init --replay` (period-based historical generation):
#### 1. Project Context Extractor (Claude Haiku)
Same as standard mode.
#### 2. Period Detector (Claude Haiku)
```
Use Task tool with:
- subagent_type: "changelog-manager:period-detector"
- description: "Detect optimal period strategy"
- prompt: "Analyze repository history to detect optimal period strategy (daily/weekly/monthly/by-release), calculate period boundaries, and present options to user."
```
**Purpose**: Analyzes commit frequency, project age, and release patterns to recommend optimal period grouping strategy.
**Output**: Period boundaries with start/end commits and dates for each period.
#### 3. Period Coordinator (Claude Sonnet)
```
Use Task tool with:
- subagent_type: "changelog-manager:period-coordinator"
- description: "Orchestrate multi-period analysis"
- prompt: "Coordinate parallel analysis of all periods by invoking git-history-analyzer for each period, managing cache, and handling retries."
```
**Purpose**: Orchestrates parallel analysis of all time periods, invoking git-history-analyzer once per period with period context.
**Sub-invocations** (managed by period-coordinator):
- For each period: Invokes **git-history-analyzer** with period boundaries
- Optional: Invokes **github-matcher** to enrich period commits
- Caches results per period for fast regeneration
#### 4. Changelog Synthesizer (Claude Sonnet)
```
Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Generate hybrid-format changelogs"
- prompt: "Generate hybrid-format CHANGELOG.md (versions with period subsections) and period-aware RELEASE_NOTES.md from multi-period analysis."
```
**Purpose**: Synthesizes period-based analysis into hybrid changelog format with version sections containing period subsections.
### Integration Flow
**Standard Mode:**
```
project-context-extractor (Haiku)
↓
git-history-analyzer (Sonnet)
↓
github-matcher (Sonnet) [OPTIONAL]
↓
changelog-synthesizer (Sonnet)
↓
Write files
```
**Replay Mode:**
```
project-context-extractor (Haiku)
↓
period-detector (Haiku)
↓
period-coordinator (Sonnet)
↓
└─→ [For each period in parallel]
git-history-analyzer (Sonnet)
github-matcher (Sonnet) [OPTIONAL]
↓
changelog-synthesizer (Sonnet)
↓
Write files
```
## Options
### Standard Mode
- `--from-beginning`: Analyze entire repository history
- `--from-tag <tag>`: Start from specific git tag
- `--empty`: Create template files without historical content
- `--config-only`: Only generate .changelog.yaml configuration
- `--force`: Overwrite existing files (backup created)
### Replay Mode (NEW)
- `--replay`: Enable historical replay mode with period-based generation
- `--period <strategy>`: Period grouping strategy
- `daily`: One entry per day with commits
- `weekly`: One entry per week (Monday-Sunday)
- `monthly`: One entry per calendar month
- `quarterly`: One entry per quarter (Q1, Q2, Q3, Q4)
- `annual`: One entry per year
- `by-release`: One entry per git tag/release
- `auto`: Auto-detect best strategy (default)
- `--calendar-align`: Align periods to calendar boundaries (default: true)
- `--skip-empty`: Skip periods with no commits (default: true)
- `--skip-merge-only`: Skip periods with only merge commits (default: true)
- `--max-workers <n>`: Concurrent period analyses (default: 3, max: 5)
- `--no-cache`: Disable caching (slower but always fresh)
- `--hybrid-format`: Generate hybrid format CHANGELOG.md (default: true)
- `--replay-in-release-notes`: Apply replay structure to RELEASE_NOTES.md (default: true)
## Examples
### New Project Setup
```bash
You: /changelog-init --empty
Claude: 📝 Initializing changelog files...
Created:
✅ CHANGELOG.md (template)
✅ RELEASE_NOTES.md (template)
✅ .changelog.yaml (configuration)
Your changelog files are ready! Next steps:
1. Customize .changelog.yaml for your project
2. Run `/changelog update` after making changes
3. Run `/changelog release` when ready to publish
```
### Retroactive Generation
```bash
You: /changelog-init --from-beginning
Claude: 📊 Analyzing repository history...
Found:
- 523 commits
- 12 tagged releases
- 24 contributors
- First commit: 2023-03-15
Generating comprehensive changelog...
✅ Generated CHANGELOG.md with 12 versions
✅ Generated RELEASE_NOTES.md with major milestones
✅ Created configuration files
Notable milestones detected:
- v1.0.0: Initial release
- v2.0.0: Major rewrite with breaking changes
- v2.5.0: Performance optimizations
```
### Replay Mode: Auto-Detection
```bash
You: /changelog-init --replay
Claude: 🔍 Analyzing repository for replay...
Repository analysis:
- Total commits: 523
- First commit: 2023-03-15 (619 days ago)
- Releases: 12 tagged versions
- Contributors: 24
- Commit frequency: 21.4 commits/week
Auto-detection results:
✅ Recommended strategy: weekly
Rationale: Consistent activity (15-30 commits/week)
Alternative strategies:
- Monthly: 20 periods, ~26 commits/period
- By-Release: 12 periods, ~44 commits/period
Use recommended strategy? [Y/n]: Y
📅 Calculating 74 weekly periods...
- Active periods: 63
- Empty periods (skipped): 8
- Merge-only periods (skipped): 3
Proceed with analysis? [Y/n]: Y
⚙️ Executing parallel analysis (3 workers)...
[Progress bar] 63/63 periods analyzed - 100% - 3m 42s elapsed
✅ Generated CHANGELOG.md (1,847 lines, hybrid format)
✅ Generated RELEASE_NOTES.md (423 lines, period-aware)
✅ Configuration saved to .changelog.yaml
✅ Cache created: .changelog-cache/ (63 period analyses)
```
### Replay Mode: Monthly Periods
```bash
You: /changelog-init --replay --period monthly
Claude: 📅 Generating changelog with monthly periods...
Period breakdown:
- March 2023: 45 commits
- April 2023: 67 commits
- May 2023: 52 commits
...
- November 2025: 23 commits (partial, → [Unreleased])
Total: 20 active months, 3 empty months (skipped)
Analyzing in parallel (3 workers)...
✅ Complete! Generated hybrid CHANGELOG.md with 20 month sections.
```
### Replay Mode: Release-Based
```bash
You: /changelog-init --replay --period by-release
Claude: 🏷️ Grouping history by releases...
Detected releases:
- v0.1.0 (2023-03-15): 15 commits
- v0.2.0 (2023-04-12): 28 commits
- v1.0.0 (2023-06-01): 67 commits (major release)
- v1.1.0 (2023-07-15): 34 commits
...
- v2.5.0 (2024-10-27): 42 commits
- Unreleased: 23 commits
Total: 12 releases + unreleased section
Analyzing releases...
✅ Generated CHANGELOG.md with 13 sections (12 releases + unreleased)
```
### Replay Mode: High-Activity Project (Daily)
```bash
You: /changelog-init --replay --period daily
Claude: ⚠️ Daily period strategy selected
Repository has 523 commits over 619 days
This will create ~619 daily periods
Recommendation: Weekly or monthly might be more readable
Continue with daily strategy? [y/N]: y
📅 Calculating daily periods...
- Active days: 287
- Empty days (skipped): 332
Proceed? This may take ~8 minutes [Y/n]: Y
⚙️ Analyzing 287 daily periods (3 workers)...
[Progress: 287/287 - 100% - 7m 53s]
✅ Generated CHANGELOG.md (3,421 lines)
⚠️ Note: Changelog is very large. Consider using weekly strategy.
```
### Replay Mode: Custom Configuration
```bash
You: /changelog-init --replay --period weekly --max-workers 5 --hybrid-format
Claude: 📋 Replay configuration:
- Period: Weekly (Monday-Sunday)
- Workers: 5 concurrent analyses
- Format: Hybrid (versions + periods)
- Cache: Enabled
- Skip empty: Yes
- Skip merge-only: Yes
⚙️ Executing with 5 concurrent workers...
[Faster execution with more parallelism]
✅ Complete in 2m 18s (vs estimated 4m with 3 workers)
```
### Replay Mode: Regenerate Specific Period
```bash
You: /changelog-init --replay-period "2024-Q3" --force
Claude: 🔄 Regenerating specific period...
Period: Q3 2024 (July-September)
- Original analysis: 2025-01-15
- Commits in period: 87
- Previous entries: 64 changes
Regenerating with current configuration...
✅ Period regenerated
✅ Updated CHANGELOG.md (merged new analysis)
✅ Backup created: CHANGELOG.2025-11-14.md.backup
```
## Generated Files
### CHANGELOG.md Template
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Initial project setup
### Changed
### Deprecated
### Removed
### Fixed
### Security
```
### Configuration File
```yaml
# .changelog.yaml
changelog:
conventional_commits: true
include_authors: true
include_commit_hash: false
categories:
- Added
- Changed
- Deprecated
- Removed
- Fixed
- Security
release_notes:
audience: "end-users"
tone: "professional"
use_emoji: true
versioning:
strategy: "semver"
auto_bump:
breaking: "major"
features: "minor"
fixes: "patch"
replay:
enabled: false
default_strategy: "auto"
performance:
enable_parallel: true
max_concurrent_periods: 3
enable_cache: true
```
### Hybrid Format CHANGELOG.md (Replay Mode)
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## Table of Contents
- **2025**
- [Week of November 11](#week-of-november-11-2025) - Unreleased
- [Week of November 4](#week-of-november-4-2025) - Unreleased
- [Week of October 21](#week-of-october-21-2024) - v2.1.0
- [Week of October 14](#week-of-october-14-2024) - v2.1.0
- **2024**
- [Month of September](#month-of-september-2024) - v2.0.0
...
## [Unreleased]
### Week of November 11, 2025
#### Added
- Real-time notification system with WebSocket support (#256, @dev2)
- Automatic reconnection with exponential backoff
- Event types: entity.created, entity.updated, entity.deleted
#### Fixed
- Memory leak in background job processor (#258, @dev1)
### Week of November 4, 2025
#### Added
- Advanced search filters with fuzzy matching (#252, @dev3)
## [2.1.0] - 2024-10-27
### Week of October 21, 2024
#### Added
- REST API v2 with cursor-based pagination (#234, @dev1)
- Backward compatible with v1 using version headers
- See migration guide in docs/api/v2-migration.md
#### Changed
- **BREAKING:** Authentication now uses JWT tokens instead of server sessions
- Sessions will be invalidated upon upgrade
- Update client libraries to v2.x for compatibility
### Week of October 14, 2024
#### Fixed
- Race condition in concurrent file uploads (#245, @dev2)
- Implemented proper file locking mechanism
#### Security
- Updated dependencies to address CVE-2024-1234 (High severity)
## [2.0.0] - 2024-09-30
### Month of September 2024
#### Added
- Complete UI redesign with modern component library (#210, @design-team)
- Dark mode support across all views (#215, @dev4)
#### Changed
- Migrated from Webpack to Vite
- Development server startup reduced from 30s to 3s
- Bundle size reduced by 22%
#### Removed
- Legacy XML export format (use JSON or CSV)
- Python 3.7 support (minimum version now 3.8)
[Unreleased]: https://github.com/user/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/user/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/user/repo/releases/tag/v2.0.0
```
## Integration
This command works with:
- `/changelog update` - Add new changes
- `/changelog release` - Prepare releases
- Git hooks - Automate updates

388
commands/changelog-release.md Normal file
View 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

412
commands/changelog.md Normal file
View File

@@ -0,0 +1,412 @@
---
description: Initialize or update CHANGELOG.md and RELEASE_NOTES.md from git history
aliases: [ "cl", "change", "release" ]
---
# changelog
Intelligent management of CHANGELOG.md and RELEASE_NOTES.md files through
AI-powered git history analysis.
## Overview
The `/changelog` command provides a comprehensive workflow for maintaining both
developer-focused changelogs and user-facing release notes. It analyzes git
commits, groups related changes, and generates appropriate documentation for
different audiences.
## Usage
```bash
/changelog # Interactive mode - guides you through the process
/changelog init # Initialize both files for the first time
/changelog update # Update files with changes since last update
/changelog review # Review and refine existing entries
/changelog release [version] # Prepare a new release with version bump
```
## Workflow Phases
### Phase 1: Discovery & Analysis
- Detects existing CHANGELOG.md and RELEASE_NOTES.md files
- Identifies last update timestamp from file metadata
- Analyzes repository structure and conventions
- Determines version numbering scheme
### Phase 2: Git History Analysis
- Collects commits since last update (or all if initializing)
- Groups commits by:
- Feature branches
- Pull requests
- Time proximity
- Semantic similarity
- Identifies breaking changes, features, fixes, and improvements
### Phase 3: Commit Understanding
- For complex or unclear commits:
- Analyzes code diffs with AI (Sonnet model for accuracy)
- Extracts semantic meaning from changes
- Correlates with issue tracker references
- Identifies user impact
### Phase 4: Change Categorization
- Organizes changes following Keep a Changelog convention:
- Added: New features
- Changed: Changes in existing functionality
- Deprecated: Soon-to-be removed features
- Removed: Removed features
- Fixed: Bug fixes
- Security: Security-related changes
### Phase 5: Documentation Generation
- Creates technical entries for CHANGELOG.md:
- Comprehensive listing of all changes
- Technical details and implementation notes
- References to PRs, issues, and commits
- Breaking change warnings
- Creates user-focused entries for RELEASE_NOTES.md:
- High-level feature descriptions
- User benefits and value propositions
- Migration guides for breaking changes
- Screenshots/examples where applicable
### Phase 6: Review & Refinement
- Presents generated content for review
- Allows interactive editing and refinement
- Validates version numbering (semantic versioning)
- Checks for consistency and completeness
### Phase 7: Finalization
- Writes updated files with proper formatting
- Creates git commit for documentation updates
- Tags release if version specified
- Generates release announcement template (optional)
## Interactive Example
```
You: /changelog
Claude: I'll help you manage your changelog and release notes. Let me analyze your repository...
📊 Repository Analysis:
- Found existing CHANGELOG.md (last updated: 2025-11-01)
- Found existing RELEASE_NOTES.md (last updated: 2025-11-01)
- Current version: v2.3.1
- 47 commits since last update
What would you like to do?
1. Update both files with recent changes
2. Prepare a new release (with version bump)
3. Review and refine existing entries
4. Generate release announcement
You: 1
Claude: Analyzing 47 commits since 2025-11-01...
🔍 Identified Changes:
- 3 new features
- 12 improvements
- 8 bug fixes
- 2 breaking changes
- 1 security update
Let me group these semantically and analyze their impact...
[Invokes git-history-analyzer agent]
[Invokes commit-analyst agent for complex changes]
[Invokes changelog-synthesizer agent]
📝 Generated CHANGELOG.md entries:
## [Unreleased]
### Added
- REST API v2 with pagination support (#234, @dev1)
- WebSocket real-time notifications (implements #189)
- Docker compose configuration for local development
### Changed
- **BREAKING:** Updated authentication to use JWT tokens instead of sessions
- Improved database query performance by 40% through indexing
- Migrated from Webpack to Vite for faster builds
### Fixed
- Memory leak in background job processor (#245)
- Incorrect timezone handling in scheduled tasks
- Race condition in concurrent file uploads
### Security
- Updated dependencies to patch CVE-2025-1234
📢 Generated RELEASE_NOTES.md entries:
## What's New
### 🚀 Real-time Notifications
Stay updated with instant WebSocket-powered notifications. No more manual refreshing!
### ⚡ 40% Faster Performance
We've optimized our database queries, making the app significantly more responsive.
### 🔒 Enhanced Security
Upgraded to JWT-based authentication for better security and seamless API access.
### 🐛 Stability Improvements
Fixed several bugs including memory leaks and timezone issues for a smoother experience.
⚠️ **Important:** This update changes how authentication works. You'll need to log in again after updating.
Would you like to:
1. Apply these changes
2. Edit before applying
3. Generate more detailed entries
4. Cancel
You: 1
Claude: ✅ Successfully updated:
- CHANGELOG.md (23 new entries added)
- RELEASE_NOTES.md (4 user-facing updates added)
Created commit: "docs: Update changelog and release notes for unreleased changes"
Next steps:
- Review the updated files
- Consider creating a release with `/changelog release v2.4.0`
- Share release notes with your team
```
## Configuration Options
Create `.changelog.yaml` in your repository root to customize behavior:
```yaml
# Changelog configuration
changelog:
# Use conventional commits for automatic categorization
conventional_commits: true
# Include commit hashes in CHANGELOG.md
include_commit_hash: true
# Include author attribution
include_authors: true
# Group commits by these criteria
grouping:
- pull_request
- feature_branch
- semantic_similarity
# Categories to use (Keep a Changelog format)
categories:
- Added
- Changed
- Deprecated
- Removed
- Fixed
- Security
# Breaking change indicators
breaking_indicators:
- "BREAKING CHANGE:"
- "BREAKING:"
- "!:" # Conventional commit breaking change
# Release notes configuration
release_notes:
# Target audience
audience: "end-users" # or "developers", "stakeholders"
# Tone
tone: "professional" # or "casual", "technical"
# Include screenshots/gifs
include_visuals: false
# Emoji usage
use_emoji: true
# Maximum entries per category
max_entries: 5
# Version management
versioning:
# Semantic versioning strategy
strategy: "semver" # or "calver", "custom"
# Auto-bump rules
auto_bump:
breaking: "major"
features: "minor"
fixes: "patch"
# AI analysis settings
ai_analysis:
# Model for commit analysis
model: "claude-4-5-sonnet" # Fast and efficient for code analysis
# Analyze commits with unclear messages
analyze_unclear: true
# Analyze large diffs for better understanding
analyze_large_diffs: true
# Threshold for "large" diff (lines changed)
large_diff_threshold: 100
# Project context integration (NEW - makes RELEASE_NOTES.md more end-user focused)
release_notes:
# Enable reading CLAUDE.md, README.md, and docs/ for context
project_context_enabled: true
project_context_sources:
- "CLAUDE.md"
- "README.md"
- "docs/**/*.md"
project_context_max_length: 5000
project_context_cache_ttl_hours: 24
# Custom instructions (highest priority - override extracted context)
emphasis_areas: ["Security", "Performance", "User Experience"]
de_emphasize: ["refactor", "chore", "build", "ci", "deps"]
include_internal_changes: false # Exclude internal changes from release notes
user_impact_keywords: ["user", "customer", "performance", "faster"]
terminology:
authentication: "sign-in system"
API: "developer tools"
```
## Agent Orchestration
**CRITICAL**: You MUST use the Task tool to invoke these agents in sequence. The workflow will fail if you don't invoke agents properly.
### 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, target audience, feature catalog, and tone guidance for generating user-focused release notes."
```
**Purpose**: Reads project documentation to understand product vision, target audience, user personas, and how to translate technical changes into user benefits.
**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 git history and group commits"
- prompt: "Extract commits since last update, group by pull request/feature branch/semantic similarity, categorize changes following Keep a Changelog format, and detect breaking changes."
```
**Purpose**: Examines commit history, groups related changes, categorizes them, and identifies breaking changes.
**Output**: Structured change data categorized as Added/Changed/Fixed/etc.
#### 3. GitHub Matcher (Claude Sonnet) - OPTIONAL
```
Only invoke if:
- GitHub remote detected
- gh CLI available and authenticated
- integrations.github.matching.enabled: true in config
Use Task tool with:
- subagent_type: "changelog-manager:github-matcher"
- description: "Match commits to GitHub artifacts"
- prompt: "Enrich commit data with GitHub Issue, PR, Project, and Milestone references using explicit matching, timestamp correlation, and semantic similarity."
```
**Purpose**: Matches commits to GitHub Issues, PRs, Projects, and Milestones using multiple strategies with confidence scoring.
**Output**: Enriched commit data with GitHub artifact references.
#### 4. Changelog Synthesizer (Claude Sonnet)
```
Use Task tool with:
- subagent_type: "changelog-manager:changelog-synthesizer"
- description: "Generate changelog documentation"
- prompt: "Generate CHANGELOG.md (technical, developer-focused) and RELEASE_NOTES.md (user-facing, benefits-focused) using project context to translate technical changes into user benefits."
```
**Purpose**: Combines all information to generate both technical and user-facing documentation, using project context to make RELEASE_NOTES.md more end-user focused.
**Output**: Final CHANGELOG.md and RELEASE_NOTES.md content.
### Integration Flow
```
project-context-extractor (Haiku)
↓
↓ [project_context]
↓
git-history-analyzer (Sonnet)
↓
↓ [git_analysis]
↓
github-matcher (Sonnet) [OPTIONAL]
↓
↓ [enhanced_analysis]
↓
changelog-synthesizer (Sonnet)
↓
↓ [final_documents]
↓
Write files
```
## Agents Used
This command coordinates multiple specialized agents:
- **project-context-extractor**: Reads project documentation (CLAUDE.md, README.md,
docs/) to understand product vision, target audience, and user-facing features
- **git-history-analyzer**: Examines commit history and groups related changes
- **commit-analyst**: Uses AI to understand complex commits and code changes (invoked automatically by git-history-analyzer when needed)
- **github-matcher**: Matches commits to GitHub Issues, PRs, Projects, and Milestones (optional, only if configured)
- **changelog-synthesizer**: Combines information to generate both technical and
user-facing documentation, using project context to make RELEASE_NOTES.md more
end-user focused
## Best Practices
1. **Regular Updates**: Run `/changelog update` frequently (e.g., weekly) to
avoid large batches
2. **Review Generated Content**: Always review AI-generated entries for accuracy
3. **Maintain Consistency**: Use the same categorization and format across
releases
4. **Version Strategically**: Follow semantic versioning for clear communication
5. **Separate Audiences**: Keep technical details in CHANGELOG.md, user value in
RELEASE_NOTES.md
## Tips
- Use `--dry-run` flag to preview changes without writing files
- Run `/changelog review` before releases to ensure quality
- Configure `.changelog.yaml` for project-specific conventions
- Tag releases in git after updating documentation
- Consider automating with git hooks or CI/CD pipelines
## Related Commands
- `/changelog init` - Initialize changelog files for a new project
- `/changelog release` - Prepare a new release with version bump
- `/git-history` - Explore git history in detail
- `/version` - Manage version numbers