release-changelog

Release Changelog

Generate a structured CHANGELOG.md from git history. Parses conventional commit messages with Why: blocks to produce a changelog that explains both what changed and why.

Process

digraph release_changelog {
    "User invokes /release-changelog" [shape=doublecircle];
    "Find last version tag" [shape=box];
    "Parse commits since tag" [shape=box];
    "Determine version bump" [shape=box];
    "Group by commit type" [shape=box];
    "Generate changelog entry" [shape=box];
    "Prepend to CHANGELOG.md" [shape=box];
    "Show result to user" [shape=doublecircle];

    "User invokes /release-changelog" -> "Find last version tag";
    "Find last version tag" -> "Parse commits since tag";
    "Parse commits since tag" -> "Determine version bump";
    "Determine version bump" -> "Group by commit type";
    "Group by commit type" -> "Generate changelog entry";
    "Generate changelog entry" -> "Prepend to CHANGELOG.md";
    "Prepend to CHANGELOG.md" -> "Show result to user";
}

Step 1: Find Last Version Tag

Run:

git tag --sort=-v:refname | head -1

If no tags exist, parse all commits from the beginning of history. Ask the user what the initial version should be (suggest 0.1.0).

Step 2: Parse Commits Since Last Tag

Run:

git log <last-tag>..HEAD --format="%H%n%s%n%b%n---COMMIT-END---"

If no tag exists:

git log --format="%H%n%s%n%b%n---COMMIT-END---"

For each commit, extract:

• subject line: parse into type, scope, and summary using pattern ^(\w+)\(([^)]+)\): (.+)$
• body: extract Why: block — everything after Why: until end of body or next blank line

Step 3: Determine Version Bump

Check the commit types collected:

• Any feat → minor bump (e.g., 1.2.0 → 1.3.0)
• Only fix, perf, refactor, etc. → patch bump (e.g., 1.2.0 → 1.2.1)
• If any commit body contains BREAKING CHANGE: → major bump (e.g., 1.2.0 → 2.0.0)

Present the suggested version to the user and let them confirm or override.

Step 4: Generate Changelog Entry

Group commits by type using this mapping:

Commit Type	Section Heading
feat	Features
fix	Fixes
refactor	Refactors
perf	Performance
docs	Documentation
chore	Maintenance
test	Tests
style	(omit from changelog)
(no match)	Other

Format each entry:

With Why: block:

- **scope**: summary
  > Why text here

Without Why: block:

- **scope**: summary

Without conventional commit format:

- commit subject as-is

Omit empty sections. Order sections: Features → Fixes → Performance → Refactors → Documentation → Maintenance → Tests → Other.

Step 5: Write to CHANGELOG.md

Compose the full entry:

## [<version>] - <YYYY-MM-DD>

### <Section>
- **scope**: summary
  > Why text

...

If CHANGELOG.md exists, prepend the new entry after the # Changelog header (or at the top if no header). If it doesn't exist, create it with:

# Changelog

## [<version>] - <YYYY-MM-DD>
...

Step 6: Show Result

Display the generated entry to the user. Ask if they want to:

1. Commit the changelog update
2. Create a git tag for the version
3. Edit anything before committing

Edge Cases

• Merge commits: Skip merge commits (Merge branch..., Merge pull request...)
• Co-authored commits: Keep Co-Authored-By out of the changelog — only parse subject and Why: block
• Multi-line Why blocks: Capture everything from Why: to end of body, trimming trailing whitespace
• Duplicate scopes: Group entries under the same scope together within each section
• No commits since last tag: Inform the user there's nothing to release