Changelog vs release notes — what's the difference?
Short answer: a changelog is a complete, dated list of every change, kept for people who need the history. Release notes are a short announcement about one release, written for people who just want to know what's new. Most products only need one of them — and which one comes down to who reads it.
What a changelog is
A changelog is a running record: every change, in order, with a date. The name comes from software — a plain text file that grows one line per change — and the format optimises for completeness and lookup. When something breaks on the 14th, the changelog tells you what shipped on the 13th.
Because it optimises for lookup, a changelog tolerates detail that would sink any other format: internal names, minor fixes, dependency bumps. Its reader has a question and is willing to scan for the answer.
What release notes are
Release notes are an announcement. One release, one note, written in the reader's vocabulary: what changed, why it matters to you, whether you need to do anything. The format optimises for being read — which means leaving things out. A release note that lists all forty commits is a changelog wearing the wrong name.
If you want the structure spelled out, the release notes template guide has four copy-paste formats.
Side by side
| Changelog | Release notes | |
|---|---|---|
| Reader | Someone looking something up | Someone catching up |
| Unit | One entry per change | One note per release |
| Completeness | Everything, always | What matters, only |
| Voice | Neutral, terse | Yours — it's an announcement |
| Failure mode | Unreadable to users | Incomplete for debugging |
Which one do you need?
Decide by reader, not by tradition:
- Your readers are developers (an API, a library, a CLI): keep a changelog. They look things up, and completeness is the feature.
- Your readers are users (an app, a service, a shop): write release notes. They will never scan a hundred entries to find the one that affects them.
- Both audiences? Write release notes on a public page and let the detailed history live where the developers already are — the repository. Duplicating the full log onto a marketing page serves neither reader.
Why one page can be both
In practice the two formats converge on the same page: dated entries, newest first, each one short. Write each entry like a release note — outcome first, in your users' words — and the page as a whole works as a changelog, because the dates and the order carry the history. The changelog examples guide shows five patterns for exactly this.
That page needs a permanent URL people can link to, search engines can index and readers can subscribe to. The Latest gives you one — write a post, hit publish, and it lands on your page, your RSS feed and the widget on your own site at the same time. Free to start, no credit card.