413 lines
12 KiB
Markdown
413 lines
12 KiB
Markdown
---
|
|
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
|