Changelog vs release notes vs product updates
Four terms for nearly the same thing. The differences are who the reader is and how the entries are ordered — and once you see that, which one you need is obvious.
2 minute read
Changelog, release notes, product updates, version history, what's new: the terms are used interchangeably, and mostly that is fine. The differences that matter are who the reader is and how the entries are ordered.
The four terms
| Term | Usually means | Reader | Ordered by |
|---|---|---|---|
| Changelog (file) | CHANGELOG.md in a repository |
Developers | Version |
| Changelog (page) | A public, dated list of what shipped | Customers and prospects | Date |
| Release notes | The write-up of one release | Customers, or developers for an SDK | — |
| Product updates | Announcements, often by email or blog | Customers | Date |
| Version history | App store or installer update notes | People deciding whether to update | Version |
Changelog vs release notes
Release notes are the account of a single release: what is in it and what it means. A changelog is all of them together, newest first. If you publish release notes on one page in date order, you have a changelog.
The distinction matters most for software people install. A library might publish detailed release notes for version 3.0, with a migration guide, while its changelog lists every version in a line or two each.
Changelog vs product updates
"Product updates" tends to mean the marketing-flavoured version: a monthly email, a blog post with a hero image. "Changelog" tends to mean the complete record, including the small fixes that would never earn a blog post.
The complete record is the more useful of the two. A customer looking for whether a bug was fixed will not find it in a monthly highlights email, and the steady drip of small entries is what shows a product is looked after. The two also combine well: every entry goes on the changelog, and the biggest ones are also announced by email.
Changelog vs version history
Version history is what an app store shows. It is ordered by version because the reader's question is "should I install this update?" A web app has no such question. Nobody chooses to update a web app, so nobody needs the version, and the date does that job instead.
Which one you need
- You ship a web app: a public, dated changelog page written for customers. No version numbers.
- You ship a library, SDK or CLI: a
CHANGELOG.mdin the repository, by version. Add a public page too if you have customers who never open the repository. - You ship a mobile or desktop app: version history in the store, because the store requires it, and a changelog page for everything the store's character limit cuts.
- You ship all of them: write each change once, at the customer's level of detail, and publish it in each place.
CHANGELOG.md vs a public changelog page goes further into keeping both without writing everything twice.
Questions
- What is the difference between a changelog and release notes?
- Release notes describe one release. A changelog is the running record of all releases, newest first. A public changelog page is, in practice, a list of release notes.
- Are product updates the same as a changelog?
- They cover the same ground. "Product updates" usually means customer-facing announcements written in marketing language, often sent by email; "changelog" usually means the complete dated record. Many companies publish one page and call it either.
- What is version history?
- The list of versions an app store or installer shows, with a short note for each. It is ordered by version number and written for people deciding whether to update an installed app.
- Which one does a SaaS product need?
- A dated public changelog, written for customers. Web apps have no versions a customer installs, so the date is the version and a title that describes the change is what matters.
Your changelog, on your own domain
One plan at $19 a month: your domain, the widget, subscriber emails, no watermark and no trackers on your readers. Writing is free — a card starts the 7-day trial when you publish.
Free tools
- Changelog Grader Score any public changelog out of 100, with the reasons.
- Release Notes Generator Turn commit messages into release notes, in your browser.
- CHANGELOG.md Validator Check a CHANGELOG.md against Keep a Changelog, line by line.