Changelog examples: a teardown of product changelogs worth copying
Most changelogs are dead. Not badly written — dead. Last entry four months ago, a category scheme that changed twice, a page nobody links to. If you've got one of those, you already know; the guilt is the first symptom.
The interesting thing about the changelogs that aren't dead is that they don't share a budget, a team size, or a tool. They share habits. Below are five well-known changelogs and the pattern each one gets right — with the specific thing a small team can steal without hiring anyone. None of these teams are our size. All of the habits scale down.
GitHub: one change, one entry, one URL
GitHub ships constantly, and its public changelog reflects that shape: small, dated entries, each one covering a single change, each one living at its own URL, browsable by category and subscribable by feed.
The pattern is atomicity plus permanence. Because every change is its own entry, a reader can scan for the one thing they care about and skip the rest. Because every entry has a stable URL, support can link to it in a ticket, a customer can link to it in their own internal docs, and it keeps answering questions for years. A quarterly round-up post can't do either of those jobs.
Steal this: one change per entry, a permanent URL per entry, and a feed. The feed matters more than it looks — it's how the people who care most (your integrators, your power users) stop having to remember to check.
Linear: cadence is the message
Linear's changelog is probably the most-cited example among small dev teams, and the reason isn't any single entry. It's the rhythm. Entries land on a steady, predictable cadence, and each one pairs a real screenshot or short clip with a few sentences of plain description — what it does, not why you should be excited.
The pattern: the changelog's first job is to answer "is this thing alive and moving?" — and cadence answers that question before anyone reads a word. A steady drumbeat of small entries signals more health than an occasional essay, because the reader learns they can rely on it. Miss the rhythm for a month and the page starts asking the question instead of answering it.
Steal this: pick a rhythm you can actually keep — weekly, fortnightly — and publish on it even when the week was quiet. "A few small fixes this week" is a real entry. Silence is also an entry; it just says the wrong thing.
Stripe: breaking changes as a contract
Stripe's API changelog treats a breaking change as a contract, not an announcement. The API is versioned, every version's changes are documented, and anything that breaks an integration comes with what changed, who's affected, and how to move.
The pattern is that the closer a change gets to breaking someone's integration, the more explicit the writing gets — the opposite of the natural instinct, which is to soften the one piece of bad news in the release. A developer reading a Stripe-style breaking-change note doesn't have to infer anything: what breaks, from when, what to do.
Steal this: a fixed template for breaking changes — what breaks, the date it takes effect, the migration path — and a visual treatment that makes them impossible to skim past. You don't need API versioning to adopt the discipline. You need the template and the nerve to state the deadline plainly.
Slack: sound like a person, especially about bugs
Slack's release notes built a reputation on their fixed-bug entries — bugs described honestly, from the user's side, often with a dry line of humour that made it obvious a human wrote them.
The durable pattern here isn't the jokes — humour is a voice choice, and forced whimsy ages badly. The pattern is that every entry is written from the reader's experience, not the codebase's. "Fixed a bug where your draft vanished if you switched channels mid-sentence" tells a reader something happened to them and it's gone. "Resolved an issue with state persistence" tells them nothing, in a tone that suggests a lawyer checked it.
Steal this: write the bug the way the user would have reported it. If a fix can't be described in terms a customer would recognise, ask whether it belongs in the customer-facing changelog at all.
Firefox: two audiences, two sections
Mozilla's release notes for Firefox have carried the same basic split for years: what's new and fixed for the person using the browser, and a separate section for the developers building on it.
The pattern: one document can serve two audiences, but only if it stops pretending they're the same reader. Your customer wants to know the export button works now. Your integrator wants to know the webhook payload grew a field. Interleave those and both readers learn to skim past half your changelog — which is training them to skim past all of it.
Steal this: if you have an API or integrations, split the entries — either separate sections in each release or a separate feed entirely. Small teams usually need nothing fancier than two headings.
What to steal: the checklist
The tools these teams use don't transfer. The habits do.
- One change per entry. If a customer could notice A without noticing B, they're two entries.
- A permanent URL for every entry, so support, docs, and customers can link to it.
- A feed (RSS or email). Your most invested readers shouldn't have to remember to check.
- A rhythm you can keep. Cadence signals health before anyone reads a word. A thin entry beats a silent month.
- A fixed template for breaking changes: what breaks, from when, what to do. More explicit as the stakes rise, not less.
- Entries written from the reader's experience, not the commit log's. If the customer couldn't observe it, reconsider whether it's an entry.
- Separate your audiences once you have integrators: customer entries and developer entries shouldn't fight for the same skim.
- Consistent categories, release after release. A returning reader should guess where a change will appear before they read it.
None of this needs a budget. All of it needs the twenty minutes a week that changelogs famously never get — which is a different problem, and one worth being honest with yourself about.
We build ChangelogPilot for teams who agree with everything above and still never find the twenty minutes — it drafts the entries from your merged PRs and leaves you the judgement calls. But none of these habits need us: they work with any changelog tool, or with nothing more than a file you update by hand.