Release notes examples for every kind of change
7 min read
The best release notes examples are short, name who is affected, and say what to do next. Below is one example for each kind of change you will ship, with the reason it works, so you can copy the shape and swap in your own facts.
Every example is invented, for a fictional invoicing app called Tidepool.
What do good release notes examples have in common?
They tell users what changed and what, if anything, to do about it, in the users’ words. Each kind of change has a different job, so the shape shifts between them.
| Type of change | The entry must say | Where it goes |
|---|---|---|
| New feature | What the reader can now do, and who gets it | Top of the notes |
| Improvement | What got faster or easier, with a number if you have one | After features |
| Bug fix | The symptom the reader saw, and that it is fixed | After improvements |
| Breaking change | Who is affected, the date, the migration | First, always |
| Security fix | What was exposed, whether it was exploited, what to do | First |
| Deprecation | What goes away, the end date, the replacement | Near the top |
| App store note | One plain sentence per change, within the character limit | Store listing |
| Internal note | What changed and what to tell customers | Support and sales channels |
What does a good new feature note look like?
A good feature note opens with what the reader can do now and names the plans or roles that get it. It skips the implementation.
Send invoices in the customer’s language. You can now choose a language for each customer, and their invoices, reminders and payment page follow it. French, German, Spanish and Portuguese are available on all plans. Set it on the customer’s page under Billing preferences.
The headline is a phrase the reader would say out loud, and the body gives scope and location. A reader who skims only the bold line still knows what shipped. The wider method is in how to write release notes.
What does a good improvement note look like?
An improvement note describes a change the reader will feel, and puts a measured number on it when one exists. Without a number, say what the reader no longer has to do.
The invoice list loads about three times faster. Accounts with over 5,000 invoices used to wait about nine seconds for the list. It now opens in about three. No action needed.
“Performance improvements” tells the reader nothing, while nine seconds against three is a claim they can check on Monday morning. The closing “No action needed” answers the question every reader has.
What does a good bug fix note look like?
A bug fix note describes the symptom the user saw, not the cause in the code, and says whether they need to redo anything. Fixes nobody noticed can go in the list at the bottom.
Fixed: reminder emails sent twice on the due date. Some customers received two identical reminders if their invoice was due on the last day of a month. This is fixed. Reminders already sent are not affected, and no one needs to resend anything.
The headline starts with “Fixed” so a scanner can sort it at a glance, and the real condition (the last day of the month) follows straight away.
How do you write release notes for a breaking change?
A breaking change note leads with the date and the affected group, then gives the migration in the same entry. It goes first in the release notes, because it is the one entry a reader must not miss.
Webhook signatures become required on 1 December 2026. From that date Tidepool stops sending unsigned webhook payloads. This affects anyone who receives webhooks without checking the
Tidepool-Signatureheader. To migrate, verify the header using the secret under Settings, Developers. If you already verify signatures, no action needed.
The date is in the headline, so it survives a skim. The affected group is named by what they do, and the last sentence releases people who are already fine, which cuts the support load. The guide to breaking changes covers how to decide whether a change counts.
What does a security fix note look like?
A security note says what was exposed, whether anyone exploited it, who is affected, and what they must do. Keep it factual and calm.
Security: password reset links could be reused. Between 3 and 17 September 2026, a password reset link stayed valid after it was used once. We found no sign that this was exploited. It is fixed, and all outstanding reset links have been invalidated. If you requested a reset in that window, request a new link.
The exact window lets a reader judge their own exposure, and the sentence about exploitation answers the first question anyone asks. “A potential issue” reads like concealment, so state what you know.
How do you write a deprecation notice?
A deprecation notice names what is being removed, gives a firm end date, and points to the replacement.
The v1 invoices endpoint is deprecated and ends on 1 March 2027.
GET /v1/invoiceskeeps working until 1 March 2027, then returns410 Gone. UseGET /v2/invoices, which returns the same fields pluscurrency. Responses from v1 now include aSunsetheader with the end date. A side-by-side migration guide is in the docs.
The endpoint name is in the headline, because the people affected search for it, and the
replacement sits beside the removal. The Sunset header tells developers which calls still use the
old version. The longer treatment is in deprecating an API.
What does an app store release note look like?
An app store note is two or three plain sentences, because most people read only the first line. Lead with the change a user would notice.
Scan a paper receipt and Tidepool fills in the amount, date and vendor. Dark mode now follows your phone setting. We also fixed a crash when opening an invoice from a notification.
The most useful change comes first, and the fix names the situation that crashed. There is no version number and no “bug fixes and improvements”. Release notes for mobile apps covers the store-specific rules.
What should an internal release note include?
An internal note is the version for support and sales. It adds what the public note leaves out: what to say, and what to avoid promising.
Multi-language invoices shipped today (all plans). Support: customers set the language under Billing preferences, and existing invoices keep their original language. Italian is not available yet. Sales: this is open to every plan, so do not position it as an upgrade.
Each audience gets its own labelled line, and the note draws the boundary (“Italian is not available yet”) before a customer asks. The internal release notes article covers format and channels.
What does a bad release note look like, rewritten?
A bad release note lists what the team did instead of what the reader gets. Fix it by moving the outcome to the front and deleting the internal vocabulary.
Before:
v3.8.1 Refactored the reminder scheduler. Fixed a race condition in
ReminderJob. Updatedbullto 4.12. Misc improvements.
After:
Reminder emails no longer go out twice. Customers with an invoice due on the last day of a month could get two reminders. That is fixed, and reminders already sent do not need to be resent. No action needed.
Also in 3.8.1:
bullupdated to 4.12.
The dependency bump dropped to a footer line, and the race condition became a symptom a customer would recognise.
How do you keep release notes consistent across releases?
Draft each entry when the change merges, and have a person approve it before it ships.
Changeloop works this way: it drafts an entry from each merged pull request with AI and holds it for a human to approve. The approval step is where an editor applies the rules above. To settle the format first, start from the release notes template, and see changelog examples for what finished pages look like.
FAQ
What are new release notes? New release notes are the message published with the latest release of a product, describing what changed and what users need to do. They cover features, improvements, fixes and breaking changes.
What is the difference between a release note and a changelog? The changelog keeps everything, for anyone who wants the full history. A release note picks from it: one release, written for the readers deciding whether it matters to them. The fuller comparison is in changelog vs release notes.
What does release notes mean? Release notes tell users what changed in a release. The phrase covers anything that explains what shipped, from an app store “What’s New” text to a page on a company website.
How long should each release note entry be? Two to four sentences is enough for most entries: the outcome, who is affected and what to do. A breaking change or a security fix may run longer because it needs a date or a migration.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.