Release notes vs changelog vs product updates: what to write where
Release notes, changelog, product updates. Most teams use the three terms interchangeably, and most of the time nothing goes wrong. The terms start to matter when you sit down to write one and can't decide how much detail to include, where to publish it, or who you're actually writing for. Those are three different questions. The three formats answer them differently, and knowing which one you're writing saves a lot of second-guessing.
Here's the short version, then the detail.
- A changelog is the complete, dated record of user-visible changes. It serves people who already use the product.
- Release notes document one specific release, in enough depth for a reader to upgrade safely.
- A product update is a curated story about recent progress. It serves the widest audience and skips most of the detail on purpose.
What a changelog is
A changelog is a running record of every change a user could notice, dated, newest first. Each entry stands alone: what changed, in a line or two, written from the reader's side rather than the codebase's. The widely-used Keep a Changelog convention is a good picture of the shape: consistent categories such as Added, Changed, Fixed, and Removed, applied release after release.
Who reads it. Existing users and the people who support them. The customer checking whether that bug got fixed. The integrator checking when a behaviour changed. Your own support person, linking an entry in a ticket instead of explaining the change again.
How deep it goes. Shallow per entry, complete over time. A line to a short paragraph is normal. The value comes from completeness and consistency rather than from any single entry being well crafted. A changelog that quietly skips inconvenient changes stops being a record and starts being marketing, and readers can tell.
Where it lives. A hosted page at a stable URL, usually
yoursite.com/changelog, ideally with a feed and a permanent link per
entry so people can subscribe and cite. We've done a
teardown of changelogs worth copying
if you want concrete models, and a guide to
writing entries people actually read.
What release notes are
Release notes belong to one release. Version 2.4 shipped; this document says what's in it. That scoping is the defining feature. Where a changelog accumulates forever, release notes have a beginning and an end, and they go as deep as the release demands: new features, changed behaviour, fixes, deprecations, known issues, and above all breaking changes with dates and migration steps.
Who reads them. Someone deciding whether to take the release, or someone the release affects. That's why the format matters most for software with real versions: libraries, APIs, CLIs, mobile and desktop apps, anything self-hosted. For those readers an upgrade is a decision with consequences, and release notes are the document they decide from.
How deep they go. As deep as safe upgrading requires. The rule of thumb: the closer a change gets to breaking someone's integration, the more explicit the writing should get. "Webhooks now need a signed secret. Unsigned webhooks are rejected from 1 October. Migration guide: link" is good release-notes writing. A vague line about improved security is not.
Where they live. Attached to the release itself. A GitHub release page, a versioned page in the docs, the app-store listing. Major versions sometimes warrant an email, because those readers need to act.
One honest complication: continuous deployment blurs this category. If you deploy twenty times a week, there's no version 2.4 for a customer to install, so "release notes" ends up describing the same entries your changelog holds. That's fine. Pick one name for the page and use it consistently. The distinction that survives is depth on breaking changes, and that discipline transfers whatever you call the page.
What a product update is
A product update is a story, told on your schedule rather than your deploy schedule. A monthly post or email that picks the three or four things worth talking about, explains why they matter, shows a screenshot, and mentions what's coming. It is openly selective. Nobody expects a product update to list every fixed bug, and it shouldn't.
Who reads it. The widest audience of the three. Customers who will never visit your changelog. Prospects on your mailing list. A trial user deciding whether the product has momentum. For many of these readers the update is doing one quiet job: showing the product is alive and moving.
How deep it goes. Shallow on mechanics, deeper on context. A changelog entry says the export button handles files over 100MB now. A product update says why exports mattered enough to rebuild, and what that opens up next.
Where it lives. The blog and the email newsletter, and it's the piece you'd link from social. It's marketing, and that's fine, because it never pretends to be the record.
The quick comparison
| | Changelog | Release notes | Product update | |---|---|---|---| | What it is | Complete dated record of user-visible changes | Everything in one specific release | Curated story about recent progress | | Primary reader | Existing users, integrators, support | Someone deciding to upgrade | Customers, prospects, newsletter | | Depth | A line or two per change | As deep as safe upgrading requires | Highlights plus context | | Completeness | Everything user-visible | Everything in the release | Deliberately selective | | Cadence | Matches your ship rate | Per release | Monthly-ish, on your schedule | | Channel | Hosted page with a feed | Docs, GitHub release, app store | Blog, email, social |
Which one does a small SaaS team need first?
Start with the changelog. The other two are derived from it.
Release notes are the changelog filtered to a single version. A product update is the changelog curated down to highlights, with narrative added. If the record exists, both become editing jobs that take minutes. If the record doesn't exist, every update starts with archaeology in your git history, trying to remember what shipped three weeks ago, and that's the step where most teams give up.
So the practical sequence for a two-to-twenty-person team looks like this. Keep a customer-facing changelog on the same rhythm you ship. Add distinct release notes only if you ship versioned artefacts that customers install or integrate against. Add a monthly product update once the changelog has enough material to curate from. One record, two derivatives.
Three mistakes worth avoiding
Publishing the record on the blog. Blog posts about releases age into an unnavigable pile. A changelog needs its own page, consistent structure, and permanent per-entry links, so a change from last March is still findable next March.
Writing the changelog in marketing voice. Enthusiasm belongs in the product update. In the changelog it reads as inflation, and once a reader suspects entries are being dressed up or left out, the record has lost the only property that made it useful.
Maintaining all three by hand from scratch. Three documents, written separately, drift apart and then die separately. Write the changelog once, properly, and let the other two borrow from it.
We build ChangelogPilot for the first layer of this stack: it reads your merged GitHub PRs, drafts changelog entries in customer voice, and leaves you the approval. The release notes and the monthly update get much easier once that record exists, whoever writes them. And if you'd rather keep the whole thing manual, the distinctions above hold with any tool or none.