zhongwei/gh-mtr-marketplace-changelog-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-mtr-marketplace-changelo…/commands/changelog.md
Zhongwei Li ec5c049ea6 Initial commit
2025-11-30 08:41:36 +08:00

12 KiB
Raw Permalink Blame History

description, aliases
description aliases
Initialize or update CHANGELOG.md and RELEASE_NOTES.md from git history
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

/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:

# 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
Reference in New Issue View Git Blame Copy Permalink