What are release notes?
Release notes are the document that goes out with a software release to tell people what changed in it. Version 2.4 ships, and the release notes say what's inside: new features, fixes, behaviour that works differently from last time, and anything that could break if the reader upgrades without acting on it. That's the whole idea. Most of what makes the format distinctive follows from one fact: release notes belong to a single release. They have a beginning and an end, and their job is done once the reader understands what this particular version means for them.
What goes in them
A useful set of release notes covers five things, roughly in this order of importance.
Breaking changes. Anything that stops working, or works differently, unless the reader does something. These get the most explicit writing in the whole document: what breaks, from what date, and what to do about it. "Webhooks now need a signed secret. Unsigned webhooks are rejected from 1 November. Migration guide: link" gives the reader everything they need to act. A vague line about improved security leaves them to find out the hard way.
New features. What's new, what it does, and where to find it.
Changes. Existing behaviour that's different now, even when the difference is an improvement. Somebody built a habit around the old behaviour, and they'd like to know it moved.
Fixes. Bugs that are gone. A line each is plenty.
Known issues. Anything you already know is wrong in this release. Naming it saves a reader an afternoon of wondering whether it's just them.
Deprecations sit between the first and third categories: not broken yet, but on notice, ideally with a date.
What stays out
Anything the reader can't observe. Refactors, test coverage, CI changes, dependency bumps that alter nothing on the surface. All of it is real work, and none of it belongs, because the reader's question is what changed for them, and for internal work the honest answer is nothing. The exception is internal work with a visible effect, such as a page that used to be slow and now isn't. Then you describe the effect.
Implementation detail stays out for the same reason. The reader doesn't need the name of the function you fixed; they need to know the symptom is gone.
Marketing stays out too. Release notes that open with how thrilled the team is have spent the reader's patience before saying anything. State what changed and let the release speak for itself.
Who actually reads them
More people than most teams expect, and nearly all of them arrive with a specific question. Someone deciding whether to take the upgrade, weighing what they gain against what might break. An integrator checking whether the API they depend on still behaves the way their code assumes. A support person, yours or a customer's, working out whether a new complaint matches a known change. The customer who reported a bug three weeks ago, checking whether this is the release that fixes it. And, reliably, your own team six months from now, trying to establish when a behaviour changed.
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 the release notes are the document they decide from. For a continuously deployed SaaS there's no upgrade decision to make, so the same writing does a quieter job: it shows the product is moving.
How they differ from a commit message
A raw commit message is written for a colleague reading the code, whereas a release note is written for a person using the product. Side by side:
Commit: fix: debounce search input to prevent duplicate requests
Release note: "Search results no longer flicker while you type."
The commit answers "what did I change in the code?" The release note answers "what does this mean for me?" Getting from one to the other is a translation job: strip the implementation, keep the effect. Tools that generate "release notes" straight from PR titles produce the first kind of sentence, which is fine for an audience of developers on a GitHub releases page and unhelpful for customers.
How they differ from a changelog
A changelog is the running, dated record of every user-visible change, accumulating across all releases. Release notes are one release's slice of that story, going deeper wherever the release demands it, especially on anything breaking. If you deploy continuously there's no version 2.4 for anyone to install, and in practice the two formats collapse into the same page. Pick one name for it and use it consistently. We've written a fuller comparison of release notes, changelogs, and product updates if you want the detail on which format belongs in which channel, and a guide to writing entries people actually read, most of which applies to release notes word for word.
The hard part isn't the format
Everything above can be learned in an afternoon. The reason release notes go unwritten is rarely the writing itself; it's the remembering. Reconstructing three weeks of shipped work from memory, or from a scroll back through merged PRs, is the step where the document dies. The useful realisation is that your repo already holds the raw material: what merged, when, and usually why. Start from that record and the notes become an editing job. That is what we built ChangelogPilot to do: it reads your merged GitHub PRs, drafts each entry in customer-facing language, sorts the breaking changes and fixes for you, and leaves you to review and publish to a hosted page. You can point it at a repo and see the first draft in a few minutes. The shape of good release notes holds whether a tool drafts them or you do.