Changelog Generation
Overview
Generate structured release notes from git history. Collects commits since the last release, categorizes them, enriches with context, and formats following the Keep a Changelog standard. Done when the new entry sits at the top of CHANGELOG.md in the format below and the user has seen it.
Process
Step 1: Determine Range
Find the boundaries of the changelog:
# Find the last release tag
git tag --sort=-v:refname | head -5
# If no tags, use first commit
git log --reverse --format="%H" | head -1
The range is: [last-tag]..HEAD (or [first-commit]..HEAD if no tags). If the user named a tag range, use it instead; a version number they give becomes the entry's heading in Step 5.
Step 2: Collect Commits
# All commits in range with full info
git log [last-tag]..HEAD --format="%H|%s|%an|%ai" --no-merges
# Merge commits (for PR-based workflows)
git log [last-tag]..HEAD --merges --format="%H|%s|%an|%ai"
Step 3: Categorize
Sort each commit into Keep a Changelog categories based on the commit message and diff:
| Category | Criteria |
|---|---|
| Added | New features, new files, new capabilities |
| Changed | Modifications to existing features |
| Deprecated | Features marked for future removal |
| Removed | Features or files removed |
| Fixed | Bug fixes |
| Security | Vulnerability fixes or security improvements |
Conventional commit prefixes map directly: feat: Added, fix: Fixed, refactor:, perf: and docs: Changed, security: Security, BREAKING CHANGE: Breaking Changes, and chore: omitted unless significant. Otherwise, read the diff to categorize.
Step 4: Enrich
For each significant entry:
- Add a human-readable description (not just the commit message)
- Note breaking changes with a
BREAKING:prefix - Link to relevant PR or issue numbers if available
- Group related commits into single entries
Step 5: Format
Follow the Keep a Changelog format:
## [version] - YYYY-MM-DD
### Added
- Description of new feature ([#PR](link))
### Changed
- Description of change ([#PR](link))
### Fixed
- Description of bug fix ([#PR](link))
### Security
- Description of security fix ([#PR](link))
### Breaking Changes
- Description of breaking change and migration path
Without a version from the user or a tag that names one, put the entries under ## [Unreleased] and say so, rather than inventing a number.
Step 6: Save
- Update
CHANGELOG.mdat the project root (create if it doesn't exist) - New entries go at the top, below the
# Changelogheader - Keep an
## [Unreleased]section at the top for ongoing work
Common Mistakes
Copy-pasting commit messages — Commit messages are for developers. Changelog entries are for users. Translate technical changes into user-visible impact.
Including internal changes — Users don't care about CI fixes, test additions, or code reformatting. Only include changes that affect the user experience or API.
Missing breaking changes — Every breaking change needs a migration path. If you can't describe how to upgrade, the breaking change isn't ready to ship.
Giant changelog entries — If a single entry is more than 2 sentences, break it into sub-bullets or summarize more aggressively.