Changelog vs release notes: what is the difference?
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.
They are not the same artifact, and the difference is not formatting. It is audience.
The short version
A changelog is a running, cumulative record of what changed. It is chronological, it is close to complete, and 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.
Release notes are a curated message about one release. They are selective, written in prose, and 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.
One is a reference. The other is an announcement.
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 |
Why the confusion is reasonable
Small teams publish one artifact that does both jobs, and for a while that is correct. A single
/changelog page with a short paragraph at the top of each entry will serve a developer looking up
a fix and a customer skimming for news. Splitting too early gives you two things to maintain and
one of them will rot.
The split becomes worth it when the two audiences start wanting different things. Some signs:
- 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.
The version that works: 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 release notes email, the in-app widget and the public page are three renderings of one thing, and nobody rewrites anything on the way to a customer.
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.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.