CHANGELOG vs release notes — the difference and which one to write

People mix these up constantly, and fairly so: both are about "what changed in the new version." But here's the fact that separates them for good.
In Google Play, the "What's new" field is capped at 500 characters per language. That's roughly one paragraph. A month of your changelog physically won't fit — and shouldn't.
Meanwhile GitHub has a button that generates release notes automatically from merged pull requests. A machine doing exactly what the changelog standard forbids in as many words: dumping raw change history.
Two documents with opposite rules. Let's sort out who needs which.
Short version: different readers
A changelog is written for whoever is upgrading. Usually a developer who pulled in your library and wants to know one thing: will this break me?
Release notes are written for whoever is using the thing. A person in the App Store, Google Play or on a release page who cares about one thing: what changed for me.
Everything else follows from that.
The axes they differ on
Not a table — five honest differences:
- Who reads it. Changelog: a developer, and "you in six months." Release notes: a user, often not technical at all.
- How long it lives. A changelog accumulates for years and gets searched for the past. Release notes live until the next release; after that almost nobody opens them.
- What goes in. Changelog: everything externally visible, including the boring parts — deprecations, closed vulnerabilities, format changes. Release notes: only what a person notices when they open the app.
- In what language. A changelog is dry and precise: "response format of
/api/orderschanged." Release notes are plain human: "orders load faster now." - Where it lives. A changelog is a file in the repo, next to the code. Release notes are a store listing, a release page, an email, a "what's new" screen.
There's a sixth, technical one: a changelog is curated by hand, while release notes are often generated. GitHub's automatic version produces a list of pull requests, a list of contributors and a link to the full comparison — handy for the project's own developers, useless to a user.
Which one you need
No fence-sitting:
You're building a library, package or API. Keep a changelog; it's mandatory. Your reader is a developer who needs the full list with compatibility notes, tied to version numbers. Release notes aren't needed at all here — the release page can simply quote the relevant chunk of the file.
You're shipping an app in a store. Release notes are mandatory — you have to fill the field anyway; the only question is whether it says "bug fixes" or something meaningful. A changelog is useful, but as an internal document.
You're running a website or web service. Formally nothing is required. Practically: keep a changelog for yourself and, every few releases, write a short "what's new" note for users.
You're solo and short on time. Keep the changelog. Release notes take two minutes to derive from it: pick the three most visible items and rewrite them in human terms. It doesn't work the other way — you can't reconstruct project history from a paragraph in a store.
How to write one from the other
The working scheme is simple and saves all the time:
- Keep the changelog as you go, as the single source of truth.
- Before shipping, read it and pick two or three items a user will actually notice.
- Rewrite them without jargon: not "fixed a race in the task queue," but "notifications no longer arrive twice."
- Everything that didn't make those three lines stays in the file and isn't lost.
A selection rule: if an item can't end with the words "...so you no longer have to," it probably doesn't belong in release notes.
The big mistake: the same text everywhere
The temptation makes sense: write once, paste everywhere. It falls apart for three reasons.
The reading moment differs. A changelog gets opened after an update, when something broke and you need to know why. A store card gets read before — while deciding whether to update at all. One text can't explain a breakage and sell an update at the same time.
The limit. Five hundred characters is three or four lines. Paste a chunk of changelog in and you get a sentence cut mid-word — and the part that gets cut is usually the important one.
Language. The store limit counts per language, so the text has to be translated too. A changelog usually lives in one language (often English), and that's fine: its reader is a developer. A user in their country needs their language, or they'll just scroll past.
Practical conclusion: don't copy, distil. The same work is described differently in the two documents — that's not duplication, it's translation from the language of changes into the language of benefit.
Do I have to keep both?
No. The mandatory one is whichever has a real reader. For a library that's the changelog; for a store app, the release notes. Add the second document only when you feel the first one isn't enough.
What do I write in the store when the release is purely technical?
The truth, in one line — "faster loading and a couple of small fixes." That's more honest than boilerplate "improvements and bug fixes," and better than inventing a feature that doesn't exist. Leaving the field empty is the worst option: people do read that card before updating.
Can release notes be fully automated?
Auto-generation makes a good draft, not a final text. It lists everything merged, internal refactors included, and speaks in commit language. Keep the generated version as your draft, and always hand-edit the top three lines — those get read, the rest mostly doesn't.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





