A changelog is the complete, dated record of what changed, entry after entry, written for people who need every detail: developers who use your library, admins who audit an upgrade. Release notes are a selection, written for the people who use the product: what's new in this release, what it lets them do, and why they should care. A software product usually wants both, and its public "changelog" page is in fact a set of release notes, one a release. What makes either one read is the same thing: telling the people who asked for a change that it's there.
A changelog: everything, in order#
A changelog lists every change a reader could be affected by, by version and date, in short lines. Libraries and
APIs keep one in their repository, often as a CHANGELOG.md in the Keep a Changelog
format, which sorts each version's changes under the same headings:
## [2.4.0] - 2026-10-20
### Added
- Export a board's posts as CSV.
### Fixed
- Votes on merged posts no longer count twice.
### Deprecated
- The `legacy_status` field, removed in 3.0.Its readers scan it for the line that concerns them, so completeness and a fixed order matter more than style. A removal or a breaking change belongs there even if nobody will celebrate it.
Release notes: what changed for the reader#
Release notes take the changes that matter to someone using the product and explain them. They are written for a reader who doesn't know your code:
- Lead with the outcome. "Send your Monday report without copying anything" says more than "Added CSV export".
- Show it. A picture of the new screen, or a short clip, beats a paragraph.
- Say who asked. "Many of you asked for this" is a thank-you, and proof that asking works.
- Leave out what nobody notices. A refactor, a dependency upgrade and most bug fixes go to the changelog.
A product's changelog page, the one users open from the app, is release notes in this sense: one entry a release or a feature, newest first, with a title and a picture.
Changelog vs release notes, side by side#
| Changelog | Release notes | |
|---|---|---|
| Reader | Developers, admins, integrators | The people who use the product |
| Covers | Every change, fixes and removals included | The changes worth telling |
| Written as | Short lines under fixed headings, per version | Short articles, with pictures |
| Lives | In the repository, or the API's docs | On a changelog page, in the app, in an email |
| Success means | Nobody is surprised by an upgrade | People use what shipped |
The entry that tells the people who asked#
Release notes reach whoever opens the page. The people who most want to read one are the people who asked for the change, and they rarely open the page.
So link each entry to the requests it delivers, and tell those people when it's published. A customer who voted for "Export to CSV" four months ago gets one email: it shipped, here is how it works. That email is what turns a feedback board from a place where requests go to wait into one people come back to.
In Swingback#
A changelog entry links the posts it delivers. When it's first published, the customers who wrote, voted for or commented on those posts hear about it, in the portal and by email, and so do the customers subscribed to the changelog. An entry can wait as a draft, be scheduled, or be published quietly for a small fix that needs no email. The portal also serves the changelog as an RSS feed.
Roadmap and changelog in the docs has the details, and the AI can draft an entry from its linked posts for you to edit.
