Keep a Changelog Generator

Keep a Changelog: a changelog written for humans

Keep a Changelog is a convention created by Olivier Lacan in 2014 (maintained at github.com/olivierlacan/keep-a-changelog) that defines how to structure a CHANGELOG.md file at the root of a project. Its guiding principle is that changelogs are written for humans, not for machines: a raw commit log is not a changelog. Each version gets its own section, similar changes are grouped together, and the newest release appears at the top.

A canonical file starts with a header, a description, an ## [Unreleased] section that accumulates pending changes, then released versions in reverse chronological order. Each version groups its entries under fixed headings:

# Changelog

## [Unreleased]
### Added
- New webhook for subscription events.

## [1.2.0] - 2026-05-20
### Added
- Bulk import endpoint.
### Fixed
- Date parser crashed on leap seconds.
### Security
- Bumped lodash to patch CVE-2026-1234.

[Unreleased]: https://github.com/acme/app/compare/1.2.0...HEAD
[1.2.0]: https://github.com/acme/app/compare/1.1.0...1.2.0

The six change categories

• Added — new features.
• Changed — changes in existing functionality.
• Deprecated — features still working but slated for removal.
• Removed — features removed in this release.
• Fixed — bug fixes.
• Security — vulnerabilities and CVE patches.

Why a curated changelog still matters

Users decide whether to upgrade by reading the changelog, not by skimming git log. A polished file builds confidence in the maintainers, and in regulated contexts (security, audit, compliance) the changelog is often the official record of what shipped and when — especially for CVE disclosures and breaking changes. The footer of compare links ([1.2.0]: .../compare/1.1.0...1.2.0) lets readers jump straight to the git diff for any release.

Curated vs auto-generated

Two cultures coexist. Conventional Changelog tools parse Conventional Commits and emit the file automatically — fast, but the prose is as good as your commit messages. Keep a Changelog is hand-curated and reads better, but takes editorial time. Many projects mix both: auto-generate a draft from commits and then polish it before tagging the release. CLI tools like kacl, the keepachangelog npm parser and GitHub Actions can lint the file in pull requests so it never falls out of format.

Changelog vs git tags vs release notes

Git tags mark versions on commits but say nothing about content. Release notes are the free-form markdown shown on the GitHub/GitLab releases UI, often per-release marketing. The changelog is a versioned file inside the repo, history-aware, that complements both: tags point to commits, release notes pitch the value, changelog explains the diff in a stable place.

FAQ

Do I write an entry for every commit? No. You write entries when you cut a release. During development, accumulate them under ## [Unreleased] and move them to a versioned heading at release time.

Can I generate it from commits? Yes, if you follow Conventional Commits, tools like conventional-changelog or git-cliff produce a Keep a Changelog-compatible output. Reviewing the draft before publishing is still recommended.

Does a deprecated item stay forever? No. Once the feature is actually removed, the entry moves from Deprecated in the older release to Removed in the release that drops it.

Should I translate the changelog? The convention is to keep a single source of truth in English and link translations from a separate docs site. Diverging copies of CHANGELOG.md per language quickly fall out of sync.