Release notes examples: six kinds of change, rewritten
Most release notes go wrong the same way: the line is accurate but only the person who wrote the code can read it. Below are six common kinds of change, each shown as the line a team often ships and a rewrite for the people who read it. All products and numbers here are invented to show the style; none are real releases.
1. A new feature
| Often shipped | Better |
|---|---|
| Added CSV export endpoint | You can now download any report as a spreadsheet. Open a report and choose Export, then CSV. |
Say what a person can do and where to find it. The word "endpoint" belongs in the developer notes.
2. A bug fix
| Often shipped | Better |
|---|---|
| fix: null check in invoice date parser (#412) | Invoices with no due date no longer show "Invalid Date" in the list. |
Describe what the reader saw, not the code you touched. If the old problem lost data, say whether anything needs repairing.
3. A deprecation
| Often shipped | Better |
|---|---|
| Deprecated v1 webhooks | Webhooks version 1 still work but stop on 1 March 2027. Switch to version 2, which sends the same events with a signature header. Settings > Webhooks shows which of yours still use version 1. |
A deprecation needs a date, a replacement and a way to find out whether it affects you.
4. A removal that breaks things
| Often shipped | Better |
|---|---|
| Removed legacy auth | Breaking: logging in with a username and password in the URL no longer works. Send the key in the Authorization header instead. Requests that still use the old form now get a 401. |
Put breaking changes first in the developer notes and start the line with the word that tells readers it matters.
5. A security fix
| Often shipped | Better |
|---|---|
| Security improvements | Update to 3.4.2 now. Versions 3.0.0 to 3.4.1 let a signed-in user read another team's file names. We found no sign it was used. No other action is needed. |
Lead with the action, name the affected versions, and say plainly what you know and do not know. Do not publish exploit details before people can update.
6. A change nobody will notice
| Often shipped | Better |
|---|---|
| Refactored importer, bumped dependencies | Developers: internal updates only, no behaviour change. Users: leave this out. |
An honest "nothing for you here" is useful. A section with nothing in it can simply be left out.
Put together: one small release
# 3.5.0 (2026-10-16)
Reports can be exported as CSV, and webhooks version 1 get an end date.
## Users
- You can now download any report as a spreadsheet. Open a report and choose Export, then CSV.
- Invoices with no due date no longer show "Invalid Date" in the list.
## Developers
- Deprecated: webhooks version 1 stop on 2027-03-01. Switch to version 2.
- Added: GET /v2/reports/{id}.csv returns the report as CSV.
- Fixed: the invoice date parser returned null for invoices without a due date.
## Team
- Customers on webhooks version 1 will need a nudge before March. Settings > Webhooks lists them.The same facts appear once per reader, in that reader's words, and the one-line summary lets anyone decide whether to read on.
Check your own
The free release notes checker flags lines that read like commits, bare issue numbers, jargon in customer notes and leftover TODOs, in your browser. The guide to writing for users, developers and your team explains the routine, and the changelog template is a copy-paste start. If you want one Markdown file per release turned into a page for each audience with feeds, that is the Release Notes Kit ($14).