Generate a Changelog from Commits
A changelog written by hand drifts from history. Generate it from the commit range between two tags so it is complete, and edit only the prose.
Procedure
- Confirm the range:
git describe --tags --abbrev=0gives the previous tag; the range isprev..HEAD. - Enforce conventional commits so the parser has something to read —
feat:,fix:,perf:,docs:,chore:,refactor:, with!or aBREAKING CHANGE:footer for breaks. - Generate with a tool that understands the convention:
git-cliff --tag v1.5.0 --unreleased -o CHANGELOG.mdOr from raw log:git log v1.4.0..HEAD --pretty=format:'%h %s' --no-merges. - Group by section in this order: Breaking Changes, Features, Bug Fixes, Performance, Documentation, Internal. Drop
chore:and pureci:noise unless the release is a tooling release. - For each entry, prefer the PR title over the raw commit subject, and append the PR number and author:
- Add retry to uploads (#482) @lee. - Call out anything the API diff flagged as breaking even if no commit said so — the changelog is where consumers look first.
- Commit
CHANGELOG.mdbefore tagging so the tag contains its own notes. - Verify nothing between the tags is missing:
git log --oneline v1.4.0..v1.5.0 --no-merges | wc -lversus the number of entries you emitted.
Pitfalls
- Merge commits inflate the list; always pass
--no-merges. - A release with no conventional prefixes produces an empty changelog — fix commit hygiene before the release, not after.
- Renaming the tag after generating makes every link in the changelog point at a dead ref.
- Silently dropping
fix:commits that lacked a PR number hides real user-facing fixes. - Auto-generated text with empty sections ("## Documentation\n-") reads as noise; omit sections with no entries.
Verification
git-cliff --tag v1.5.0 --unreleased | head -40 && \
test "$(git log v1.4.0..HEAD --oneline --no-merges | wc -l)" -ge "$(grep -c '^- ' CHANGELOG.md)"
Every non-chore commit is represented exactly once, breaking changes appear at the top, and the tag v1.5.0 exists on the same commit as the committed changelog.
Report: "Generated CHANGELOG for v1.5.0 covering commits across PRs; breaking changes listed first."