Changelog Generator

What this tool is used for

• Producing a Keep-a-Changelog section for a release.
• Getting the heading and grouping conventions right.
• Producing a consistent entry format across releases.
• Turning a list of merged changes into a readable release note.
• Producing an entry to paste into an existing CHANGELOG file.

Frequently Asked Questions

Which format does it produce?

Keep a Changelog, the convention behind most `CHANGELOG.md` files: a version heading with a date, then grouped sections — Added, Changed, Deprecated, Removed, Fixed, Security. Grouping by *kind of change* is what makes it scannable.

Why not just paste the git log?

Because commit messages are written for reviewers, not users. A log full of "fix tests" and "address review comments" is noise to someone deciding whether to upgrade. A changelog is an editorial summary — that is the whole value.

How does this relate to semantic versioning?

Directly: a Removed or breaking Changed entry means a major bump, anything under Added means a minor, and a changelog with only Fixed entries is a patch. If the sections do not justify the number you were about to release, one of them is wrong.

What should a Security entry say?

What was vulnerable, which versions were affected, and what to do — with a CVE reference if one exists. Say enough for someone to judge urgency without publishing a working exploit, and never bury a security fix inside a general "Fixed" bullet.

Where do the dates come from?

You set them, in ISO 8601 (YYYY-MM-DD). That format is unambiguous internationally — 03/04/2026 is March or April depending on the reader — and it sorts correctly as plain text, which matters in a file that grows downwards forever.

What are conventional commits?

A message convention — `feat:`, `fix:`, `BREAKING CHANGE:` — that makes the history machine-readable. It is what lets a tool group entries and infer the next version number without anyone maintaining the file by hand.

Should the changelog be written for users or developers?

Users. A commit log describes what changed in the code; a changelog describes what changed for someone using the software. That difference is why a good entry often bears little resemblance to the commit that caused it.

Common errors and gotchas

• Writing entries from commit messages rather than for readers, which produces a log nobody reads.
• Omitting breaking changes as a distinct category, which is the one thing a reader is scanning for.
• Using a date format other than ISO, which makes the file harder to sort and parse.
• Adding entries under Unreleased and never promoting them at release time.
• Describing what changed in the code rather than what changed for the user.