Keep a Changelog is a naming convention for release notes: six labelled categories for what kind of change happened, an Unreleased section at the top for what has not shipped yet, newest versions listed first, and a date on every entry. It pairs naturally with semantic versioning, though nothing forces you to use either alongside it.
This page is one part of a larger guide. For the whole subject in one place, see changelogs and release notes.
What are the six change types?
The convention names six kinds of change and asks you to sort every entry into one of them, rather than inventing your own categories per release.
| Type | What it covers | Example entry (illustrative) |
|---|---|---|
| Added | A new feature that did not exist before | "Added CSV export for the roadmap board." |
| Changed | A change to something that already existed | "Changed the default sort order on the roadmap to newest first." |
| Deprecated | A feature still present, on its way out | "Deprecated the weekly digest email; it will be removed in a future release." |
| Removed | A feature taken away | "Removed the legacy weekly digest email." |
| Fixed | A bug fix | "Exporting a board with zero votes no longer fails." |
| Security | A fix for a vulnerability | "Patched a security issue in the export endpoint." |
Every entry above is invented for this article to illustrate the shape, not copied from any real product's changelog. The value of naming all six up front is that a contributor writing a release does not have to decide, each time, what to call the bucket a change belongs in. It has already been decided.
Fixed and Security look similar and are worth telling apart. Fixed covers ordinary bugs: something behaved wrongly and now does not. Security covers a fix for something that could have been exploited, and the convention exists partly because those entries deserve to be found quickly by someone auditing what shipped, without scrolling past every other bug fix to find them.
What does the Unreleased section do?
At the top of the file, above the newest dated version, sits a section called Unreleased. Entries go there as soon as they merge, before there is a version number or a date to attach them to. When a release actually ships, that section is renamed to the new version and its date, and a fresh, empty Unreleased section is opened above it.
Keep an Unreleased section at the top to track upcoming changes.
Keep a Changelog 1.1.0
The point of this is not aesthetic. It solves a specific, ordinary failure: a change ships, and writing it up gets pushed to "before the next release," and then the release happens and nobody remembers to write it up because the moment has passed. Recording it in Unreleased the day it merges removes that gap entirely; there is no separate step to forget.
Why does it insist on newest-first order?
Because that is the only order a reader actually uses a changelog in. Nobody opens a changelog to read the origin story of a product from version one onward; they open it to answer "what changed since I last looked," and the answer to that question is always at the top if the newest version is listed first. A changelog in chronological, oldest-first order makes the reader scroll past everything they already know to reach the one thing they came for.
How does semantic versioning fit alongside it?
Semantic versioning gives a version number three parts: MAJOR.MINOR.PATCH. The convention most teams pair with Keep a Changelog is to let the categories decide which part moves. A Fixed-only release bumps the patch number. A release with an Added or a non-breaking Changed bumps the minor number. A release with a breaking Changed or a Removed bumps the major number.
Nothing about Keep a Changelog requires semantic versioning specifically, and nothing about semantic versioning requires the six categories. They are two separate conventions that happen to answer each other's obvious next question: the categories tell you what kind of change happened, and semantic versioning gives that a consistent number to travel under.
One payment, no subscription, unlimited products.
Is it worth adopting for a small product?
Honestly, only partly. The six categories are useful once you have several contributors shipping in parallel and need everyone sorting entries the same way without asking. For a product with one or two people writing every release note themselves, that coordination problem does not really exist yet, and forcing every entry into exactly one of six named buckets can turn into ceremony that slows down writing the note more than it helps anyone read it.
What is worth keeping regardless of team size is the newest-first order and a date on every entry. Those two habits cost nothing extra to follow and fix the two most common complaints about changelogs: not knowing what is recent, and having to scroll past history to find it. The category names and the Unreleased section are the parts to adopt once coordination actually becomes the problem, not before.
The writing itself, describing the effect of a change rather than the commit that produced it, matters more than which category scheme sits above it. That craft is covered in changelog examples, and it applies whether you use six named categories, three of your own, or none at all.
Frequently asked questions
Do I have to use all six categories?
No. Some teams use three or four and skip the ones they rarely need, most often Deprecated. The value is in having a fixed, agreed set at all, so contributors are not inventing new category names release after release. Which specific set you use matters less than using the same one every time.
What goes in Unreleased if nothing has shipped yet?
Nothing. An empty Unreleased section is normal and expected between releases; it only fills up as changes merge. Some teams remove the heading entirely when it is empty and re-add it the moment the first entry lands, rather than leaving a permanently visible empty section.
Does using this convention require semantic versioning too?
No, they are independent. You can sort entries into the six categories while using date-based version numbers, build numbers, or any other scheme. Semantic versioning is simply the most common pairing, because the categories already tell you whether a change is breaking, additive, or a fix, which is exactly the information semantic versioning needs to pick the next number.
Is Security different from a normal bug fix?
Yes, in what it is for rather than in mechanics. Security is reserved for fixes to something that could have been exploited, kept separate from ordinary Fixed entries so anyone checking what security-relevant changes shipped in a release can find them without reading every bug fix. The entry itself should confirm a fix shipped without detailing the vulnerability while it might still affect anyone who has not updated.
Can I start using this convention partway through a product's life?
Yes. There is no requirement to reclassify old entries; most changelogs that adopt the convention simply start applying it from the next release onward and leave earlier, unsorted entries as they are. Retrofitting history is optional and rarely worth the effort compared with getting new entries right going forward.