Keep a Changelog: The Standard Explained

What is Keep a Changelog?

Keep a Changelog is an open convention for writing changelogs, created by Olivier Lacan. It isn't a tool or a library — it's a shared set of rules that thousands of open-source projects follow so that any developer can read any changelog and instantly know where to look. New to the concept entirely? Start with what a changelog is.

The whole standard rests on one idea: changelogs are for humans, not machines. A git log is a machine record of every commit. A changelog is a curated, readable summary a person can scan.

The core principles

• One section per version, newest at the top.
• Every version is dated in ISO format (YYYY-MM-DD).
• Changes are grouped by type, not dumped in one list.
• An Unreleased section sits at the top for changes that are merged but not yet shipped.
• Write for people — describe the impact, not the implementation.

The six standard categories

Keep a Changelog defines exactly six headings. Using the same six everywhere is what makes changelogs skimmable:

• Added — new features.
• Changed — changes to existing functionality.
• Deprecated — features that will be removed soon.
• Removed — features removed in this release.
• Fixed — bug fixes.
• Security — vulnerabilities addressed.

You don't need all six in every release — just the ones that apply. For the broader set of conventions (Markdown vs JSON, linking versions, flagging breaking changes), see our changelog format guide.

The Unreleased section

The Unreleased block is the trick that keeps a changelog current instead of forgotten. As you merge pull requests, you add a line to Unreleased. When you cut a release, you rename that block to the new version and date, then open a fresh empty Unreleased. The changelog is always up to date because updating it is part of shipping, not a separate chore.

A full example

Notice how a reader can answer "what's new since 1.3?" in seconds. That readability is the entire point.

Common mistakes

• Dumping raw commit messages. fix: null check in ExportService means nothing to a user. Translate it.
• Skipping dates. A version number without a date makes it impossible to reason about timing.
• Batching months of changes. Update the Unreleased block as you go, not once a quarter.
• Inventing your own categories. Custom headings defeat the shared-format advantage.

Keep a Changelog vs release notes

The Keep a Changelog format is technical and complete — ideal for developers reading a repo. Release notes are the curated, user-facing version of the same release. Many teams keep both: a strict CHANGELOG.md for developers and friendly release notes for users, generated from the same set of merged changes.

Automating it

Because the format is so regular, it automates well. Our open-source commit-changelog-action turns Conventional Commits into a grouped changelog, and ChangeNote turns the same commits into polished, user-ready release notes you review and publish.

Frequently asked questions

What is Keep a Changelog?

An open standard for how to write and structure a changelog file: one dated section per version (newest first), changes grouped under Added / Changed / Deprecated / Removed / Fixed / Security, and an Unreleased section at the top for upcoming changes.

What are the Keep a Changelog categories?

Six: Added (new features), Changed (changes to existing functionality), Deprecated (to be removed soon), Removed (removed now), Fixed (bug fixes), and Security (vulnerabilities addressed).

Is Keep a Changelog the same as Semantic Versioning?

No, but they pair together. Keep a Changelog defines how you describe changes; Semantic Versioning (MAJOR.MINOR.PATCH) defines how you number releases. Most projects use both.