Changelogator

Changelogator

Generate a structured changelog from git commits following Keep a Changelog format.

By default, output the changelog in chat for the user to review — do not write to CHANGELOG.md unless the user explicitly asks.

Workflow

1. Find the last tag: git tag --sort=-v:refname | head -1
2. Retrieve commits: git log <tag>..HEAD --format="---COMMIT---%n%H%n%s%n%b" --reverse (if no tag, use git log --format="---COMMIT---%n%H%n%s%n%b" --reverse)
3. Parse each commit subject using the format below
4. Classify into changelog categories using the mapping table
5. Detect breaking changes: ! after type (e.g., feat!) or BREAKING CHANGE in body
6. Suggest semver bump based on the rules below
7. Write a summary paragraph: 2–3 sentences, plain language, user-focused — highlight the most impactful changes, skip internal/technical ones
8. Build GitHub compare URL: git remote get-url origin + strip .git + append /compare/<prev-tag>...<new-tag> (only if remote is a GitHub URL)
9. Generate the markdown changelog
10. Output in chat for validation

Commit Format

Expected format (from commitor):

<emoji> <type>(<scope>): <description> (<TASK-XXX>)

Parse using these parts:

• Emoji: leading Unicode emoji
• Type: word after emoji (feat, fix, patch, etc.)
• Scope: optional, inside parentheses after type
• Breaking: ! between type/scope and :
• Description: text after :
• Task number: optional, inside parentheses at end of subject

Category Mapping

Map commit types to changelog categories (consistent with commitor):

wip commits are excluded from changelogs — they don't represent releasable changes.

Localization

When generating in French, use these category names:

Semver Rules

Suggest a version bump based on the most significant change:

Apply to the last tag version. If no tag exists, suggest v0.1.0.

Output Template

## vX.Y.Z - YYYY-MM-DD

<2–3 sentence summary of release highlights>

**GitHub compare:** https://github.com/{owner}/{repo}/compare/{prev-tag}...vX.Y.Z

### ✨ Added
- **scope**: description
- description without scope

### 🔨 Changed
- **scope**: description

### 🐛 Fixed
- description

### 🔥 Removed
- description

### ⚙️ Technical
- description

Output Rules

• Rewrite descriptions — do not copy commit subjects verbatim. Rephrase into clear, human-readable sentences. Use backticks for code references (skill names, commands, files, config keys). Capitalize the first word.
• Omit empty categories — only show categories that have commits
• Scope as bold prefix when present: - **scope**: description
• No scope: just - description
• Skip merge commits — ignore subjects starting with Merge
• Include task numbers when present: - **scope**: description (TASK-123)
• Language: English by default; if the existing CHANGELOG.md or commits are in another language, match that language
• Summary paragraph: 2–3 sentences, plain language, user-focused. Highlight the most impactful user-facing changes; skip wip, build, refactor, test, docs. End with a short transition if there are minor fixes (e.g., "Plus, a set of fixes.")

Edge Cases

• No tag found: use all commits and suggest v0.1.0
• No commits since tag: output "No changes since <tag>."
• Unrecognized format: classify under "Other" with the full subject as description
• Multiple breaking changes: still one major bump, list all in a ### ⚠️ Breaking Changes section at the top

Example

Input commits (from git log v1.2.0..HEAD):

✨ feat(auth): add OAuth2 login with Google (NTT-128)
🐛 fix(exports): prevent duplicate rows in CSV export
🔨 patch(ui): improve loading spinner animation
♻️ refactor: simplify database connection pooling
🔥 remove(api): drop deprecated v1 endpoints

Output:

## v1.3.0 - 2026-02-12

This release brings Google OAuth2 login, making it easier to get started without a password. The deprecated v1 API endpoints have been removed — make sure to migrate to v2 before upgrading. Plus, a set of fixes and UI polish.

**GitHub compare:** https://github.com/owner/repo/compare/v1.2.0...v1.3.0

### ✨ Added
- **auth**: `OAuth2` login with Google provider (NTT-128)

### 🔨 Changed
- **ui**: Improve the loading spinner animation

### 🐛 Fixed
- **exports**: Fix duplicate rows appearing in CSV exports

### 🔥 Removed
- **api**: Drop deprecated `v1` API endpoints

### ⚙️ Technical
- Simplify database connection pooling

Suggested version: v1.3.0 (minor bump — contains new feature)