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.