Changelog

Generates human-readable changelogs from git commit history following Keep a Changelog format and Conventional Commits conventions.

Capabilities

1. Generate changelog from git commits (date range, tag range, or since last release)
2. Update existing changelog by adding new entries to the Unreleased section
3. Create new changelog with proper structure and initial content
4. Translate commits from developer language to user-friendly descriptions

Auto-Detection Workflow

When invoked without arguments, automatically detect and execute:

/changelog (no args)
    |
    +-- Check: Does CHANGELOG.md exist?
    |       |
    |       +-- NO  --> Create New Changelog (full git history)
    |       |
    |       +-- YES --> Check: Are there new commits since last entry?
    |               |
    |               +-- YES --> Update Unreleased section
    |               +-- NO  --> Report "Changelog is up to date"
    |
/changelog [version]     --> Convert Unreleased to version release
/changelog [date range]  --> Generate entries for specific period

Default behavior requires zero input — just run /changelog and the right thing happens.

Creating a New Changelog

1. Verify no CHANGELOG.md exists at project root
2. Detect git remote URL for footer links: git remote get-url origin
3. Get all tags: git tag --sort=-v:refname
4. Analyze git history to gather commits
5. Categorize commits using Conventional Commits mapping (see references/changelog_format.md)
6. Generate CHANGELOG.md with:
   • Header explaining the format
   • Unreleased section with categorized changes
   • Version sections for each existing tag (if any)
   • Footer links to GitHub comparisons
7. Verify: Count entries match expected categorized commits
8. Write CHANGELOG.md to project root

Updating an Existing Changelog

1. Read existing CHANGELOG.md
2. Identify last documented version from existing content (look for ## [x.y.z] headers)
3. Get corresponding tag: git tag --sort=-v:refname | head -1
4. Gather commits since that point: git log --oneline <last-tag>..HEAD
5. If no new commits: report “Changelog is up to date” and exit
6. Categorize new commits using Conventional Commits mapping
7. Add entries to Unreleased section (create section if missing)
8. Preserve all existing content exactly
9. Verify: New entry count matches new commit count (minus filtered)
10. Write updated CHANGELOG.md

Generating a Release Entry

1. Gather commits for the release range
2. Group by change type (Added, Changed, Fixed, etc.)
3. Filter noise (merge commits, CI/CD changes, refactors unless significant)
4. Translate technical commits to user-friendly descriptions
5. Format as new version section with ISO 8601 date

Git Analysis Commands

# All commits since last tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "")..HEAD

# Commits between tags
git log --oneline v1.0.0..v1.1.0

# Commits in date range
git log --oneline --since="2024-01-01" --until="2024-01-31"

# Get current tags
git tag --sort=-v:refname | head -10

Commit Categorization

Map Conventional Commits prefixes to Keep a Changelog sections. See references/changelog_format.md for the full type-to-section mapping, writing style guidelines, and anti-patterns.

Quick reference:

Always include: features, user-facing bug fixes, breaking changes, security fixes. Always filter: merge commits, internal refactors, test changes, CI config, typos.

Translate technical commits to user-friendly language:

• fix(auth): resolve JWT expiry edge case -> “Fixed session timeout issues for long-running sessions”
• feat(api): add /users endpoint -> “Added user management API endpoints”

Output Format

Generate changelog following this structure:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

## [1.0.0] - YYYY-MM-DD

### Added
- Initial release features

[Unreleased]: https://github.com/owner/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/owner/repo/releases/tag/v1.0.0

Examples

References