Release notes
Release notes are the document published with a software release that tells its users what changed: the features added, the behaviour altered, the bugs fixed and the known issues that remain, written for the people who use the product rather than the people who built it. They are organised by what the reader will notice, not by the order the work was done.
The longer version
Good release notes are written from the outside in. Each entry names what the user can now do, what now behaves differently and what they might need to change, in the user's vocabulary: the export button, not the export service; the report, not the ticket entity. Bug fixes describe the symptom that is gone, since the reader knows the symptom and never saw the cause. Known issues list what is still broken and any workaround. The version, the date, and how the release arrives, whether it rolls out on its own or must be installed, sit at the top.
Release notes are confused with a changelog. A changelog is the running record of every notable change, one terse line per change, grouped by version with the newest first, kept with the code or the docs for developers and for anyone integrating with the product. Release notes are written per release, curated, and organised by what matters to the reader. A changelog entry says the upload endpoint now resumes an interrupted transfer from the last confirmed chunk; the release note says large uploads no longer fail on a slow connection. Many products keep both, and produce the second from the first.
Copied ticket titles give the reader fix null pointer in invoice service and tell them nothing. A list of what the team is proud of buries the behaviour change that breaks somebody's workflow, which was the one entry the affected user needed. Notes written after the release rather than as part of it mean support learns about the change from a customer. The fix is a release-note field on the ticket, filled in when the work is done by the person who knows what changed, so that the document is assembled at release time rather than authored then.
Common questions
What is the difference between release notes and a changelog?
A changelog is the complete record of every notable change, one line each, grouped by version and written for developers. Release notes are a curated document per release, written for users, that says what they will notice and what they may need to do. A changelog entry describes a change in the terms an integrator uses; a release note describes it in the terms a user sees.
Who writes release notes?
The person who knows what changed and for whom, which is the developer or product owner on each ticket, writing a one-line note when the work is done. Somebody with the user's vocabulary, often a product manager or a technical writer, then edits the collected lines into the document. Notes written from scratch at release time by someone who was not in the work are the ones that copy ticket titles.
What should release notes include?
The version and date, how the release arrives, new capabilities described as what the user can now do, changes in existing behaviour with anything the user must do in response, fixed bugs described by the symptom that is gone, and known issues with workarounds. Internal refactors, dependency bumps and tooling changes stay out of release notes; a dependency or internal change that integrators will notice goes in the changelog.
When should release notes be published?
With the release, so that a user who meets the changed behaviour can find the explanation the same day, and support has read the notes before the first ticket arrives. The draft is assembled from the per-ticket notes during the release readiness work, reviewed by support and product before the go/no-go, and published when the deployment is confirmed. Notes written afterwards describe a change support has already heard about from a customer.
Do internal releases need release notes?
A release with internal users still has readers: the support desk, the sales team demonstrating the product, the colleagues who dogfood it, and the tester who needs to know what changed before the regression run. The notes for an internal release are shorter and can use the team's vocabulary, and they still list changed behaviour, fixed defects and known issues, because the same questions arrive from inside the company.
Bug reports that arrive ready to triage.
Collect replay, console, network and browser context with the Free plan.