Changelog vs release notes: what is the difference?
5 min read updated
A changelog is a running, cumulative record of everything that changed, written for someone looking something up. Release notes are a curated message about one release, written for someone deciding whether it matters to them. The difference is audience, not formatting, and most teams need both: one as a reference, one as an announcement, derived from the same entries.
Most teams end up with one of these by accident and the other by request. You start with a changelog because a developer wants a record of what shipped. Months later someone in support asks why customers did not know about a feature that has been live since April, and now you need release notes.
Changelog vs release notes, side by side
| Changelog | Release notes | |
|---|---|---|
| Reader | Someone looking something up | Someone deciding whether to care |
| Scope | Everything that changed | What is worth saying about this release |
| Cadence | Continuous, per merge or per release | Per release, and only releases worth announcing |
| Tone | Terse, factual, often imperative | Explanatory, sometimes persuasive |
| Lifespan | Permanent, and read years later | Read in the first week, then archived |
| Lives in | The repo, a docs site, a /changelog page | Email, in-app, a blog post, a release page |
| Fails by | Being incomplete | Being boring, or arriving after the fact |
What is a changelog?
A changelog is a chronological, close-to-complete record of what changed, newest first, with each entry typed (added, changed, deprecated, removed, fixed, security) and dated. Its reader has already decided they care. They are looking something up: when a behaviour changed, whether a bug is fixed, which version introduced a flag. Completeness is the whole value, which is why the Keep a Changelog convention spends most of its one page on structure and almost none on prose.
What are release notes?
Release notes are a selective, written-in-prose message about one release. Their reader has not decided anything yet. They are deciding whether this release matters to them, and whether they have to do anything about it. Selection is the whole value: a release note that lists everything is a changelog with paragraphs, and it fails the reader the same way a changelog that skips things fails its reader. How to write release notes is about the selection and the wording.
Do you need both a changelog and release notes?
You need both once your two audiences want different things; until then one artifact doing both
jobs is correct. Small teams publish a single /changelog page with a short paragraph at the top of
each entry, and for a while that serves a developer looking up a fix and a customer skimming for
news equally well. Splitting too early gives you two things to maintain and one of them will rot.
The split becomes worth it when these start happening:
- Your changelog entries have grown explanatory paragraphs that developers scroll past.
- Or the opposite: your release announcements have started listing dependency bumps.
- Support is copying entries into emails and rewriting them on the way.
- Someone asks for “just the breaking changes” and you cannot filter for them.
That last one is the real tell. If nobody can answer “what changed that affects me” without reading everything, you have one artifact doing two jobs badly.
One source, two views
The mistake is to treat them as two documents. They are two views over the same set of changes.
Write the changelog as you go, one entry per meaningful change, each tagged with what it is: fixed, added, changed, removed, deprecated, security. Keep the entries short enough that writing one is not a decision. Then, at release time, release notes are a selection and a rewrite: take the entries that matter to a human, group them by what they let someone do, and put the reason at the top.
This has a practical consequence. If the changelog is the source, it needs to be structured data, not a hand-maintained page. An entry needs a type, a date, a version, and a way of saying who it is for. Once it has that, the public page, the in-app widget and the RSS or JSON feed are three renderings of one thing, and nobody rewrites anything on the way to a customer. A release notes email can quote the same entry, from whatever tool sends your email. Changelog automation is about which of those steps a machine should own. That is the whole argument for treating a changelog as a feed rather than a page. It is also, transparently, what we build, so read that as an interest rather than a neutral survey.
If you only have time for one
Write the changelog. It is cheaper per entry, it is useful the day you write it, and release notes can be derived from it later. The reverse is not true: you cannot reconstruct a year of changes from twelve announcement emails, and people will ask you to.
Keep it in a fixed format so the derivation stays possible. Our changelog examples page collects entries from teams that do this well, and the release notes template is the shape we use when turning a set of entries into something worth sending.
A note on naming
None of this is standardised, and you will find “release notes” used for a running list and “changelog” used for a quarterly announcement. Arguing about the words is not worth it. Decide which of the two jobs each of your artifacts is doing, name it whatever your team already calls it, and make sure neither is quietly doing both.
Whichever you publish, the surface it lands on is a separate decision, taken in how to build a changelog page.
FAQ
Is a changelog the same as release notes? No. A changelog is the complete record, read by people looking something up; release notes are the selected announcement, read by people deciding whether to care. The same change appears in both, worded differently for each reader.
Can release notes be generated from a changelog? Yes, and that is the right direction. Select the entries a human would care about, group them by outcome, rewrite the headline. The reverse, reconstructing a changelog from announcements, loses everything the announcements left out.
Where should a changelog live?
Somewhere permanent and linkable that the reader can reach without a repository: a /changelog
page, a docs site, or a feed that renders in several places. A CHANGELOG.md alone reaches
contributors, not customers.
Should a changelog include internal changes? Yes, at the bottom, one line each. The changelog is the complete record. Release notes can keep them too, in a short last section, as long as the changes a reader will notice come first.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.