A changelog entry for a breaking change has to answer four questions in its first two lines: what stops working, who it affects, the date it stops, and what to do instead. Everything else in the entry is context. The reason it takes discipline is that no widely used changelog standard offers a category called Breaking — Keep a Changelog 1.1.0 lists six types of change and none of them is named that — so the weight falls on the entry's title and its opening sentence rather than on a label a reader can filter by.
Keep a Changelog 1.1.0 defines six types of change: Added for new features, Changed for changes in existing functionality, Deprecated for soon-to-be removed features, Removed for now removed features, Fixed for any bug fixes, and Security in case of vulnerabilities. A breaking change is not a seventh type, it is a property that any of Changed, Removed or Security can carry. The same holds in this product, whose changelog tags are NEW, FIX, IMPROVEMENT and REMOVED: a removal goes under REMOVED, and a behaviour that changed under the same name has no tag of its own at all.
If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.
A changelog migration is four decisions, not a copy and paste: where the entries live from now on, what address each one answers at, what happens to the links people already shared, and who writes the next entry.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
Entries that fail readers usually fail on the fourth and sixth of those. A changelog that announces a removal without a date leaves every reader with the same unanswered question, and each of them has to ask it separately in support.
Keep a Changelog recommends that upgrading be survivable in two steps: a version that lists the deprecations, then a version where those deprecations become removals. That shape works for a changelog too. The deprecation entry announces the end date while the old path still works, and the removal entry, published on that date, says the same thing in the past tense. A reader who acted on the first entry sees the second one as confirmation rather than as news.
| Moment | Tag that fits | What the entry must state |
|---|---|---|
| Deprecation announced, old path still works | IMPROVEMENT, with a deprecation note in the body | The replacement, and the calendar date the old path stops working |
| Behaviour changes under the same name | No tag names this; the title has to say it plainly | The old value, the new value, and the date the change went live |
| Old path removed | REMOVED | That it is gone, the date it went, and where the announcement was made |
| Removal forced by a security issue | REMOVED, and the body says why | What was vulnerable, in enough detail to act on and no more |
The title of a breaking-change entry is the part most readers see, because a changelog page is scanned before it is read. A title like "API improvements" hides the change; a title like "The replies metric is removed on 1 December" carries the whole announcement, and the body only has to supply detail. Naming the thing and the date in the title also survives the entry being lifted into an email, an RSS reader or a search result, where the body may be truncated.
Keep a Changelog has one more convention worth borrowing for the worst case: a version pulled because of a serious bug or security issue is marked with a bracketed YANKED tag next to its heading, on the grounds that it is loud, and being surrounded by brackets makes it easy to parse programmatically. A breaking change announced quietly and a version withdrawn quietly cause the same problem, which is a reader who finds out from a failure instead of from the changelog.
A breaking change is any change that makes previously working usage stop working: a removed endpoint or field, a renamed setting, a stricter validation rule, a changed default, or a response shape that existing code parses. In a changelog it is written as an entry that states what stops working, who is affected, the date it takes effect and the replacement path. It is a property of an entry rather than a category, because the standard categories describe what happened, not how much it hurts.
No. Keep a Changelog 1.1.0 defines six types of change: Added, Changed, Deprecated, Removed, Fixed and Security. A breaking change is recorded under whichever of those describes it, usually Changed or Removed, and the fact that it breaks something is stated in the entry itself. The standard does say that if you do nothing else, you should list deprecations, removals and any breaking changes.
Yes. Bundling a breaking change into a list of unrelated improvements means readers who skim the heading never learn about it. One entry, one breaking change, with a title that names the thing and the date. If a single release contains three breaking changes, that is three entries, and the release notes can link to all three rather than summarising them into one line.
Long enough for an affected reader to notice the entry, schedule the work and ship it, which is a question about the audience rather than about the code. What matters more than the length is that the notice period is a calendar date stated when the deprecation is announced, repeated in the documentation for the old path, and honoured. A date that moves twice teaches readers to ignore the next one.
Somebody deciding whether to buy your product reads the changelog for something your marketing pages cannot tell them: whether anyone is still working on it, and what happens to them when something changes.
A changelog entry that links well converts better than one that sells. The rule is destination, not persuasion: link where the reader goes to use the thing, and cut every link that exists to move them somewhere you wanted them.
