Prompt Notebook

Release notes · Product management · Templates

How to write release notes, with a filled-in example

By T. Krause

Release notes tell the people using your product what changed. Here is how to turn ticket titles into plain sentences, what to leave out, what you can't leave out, and an invented release where eleven tickets become seven lines.

Release notes tell the people using your product what changed in a version. To write them, go through the tickets in the release and keep the ones a customer would notice. Rewrite each one as what the customer can now do, or what no longer goes wrong. Group the lines under New, Improved and Fixed, put the version number and date at the top and put the newest release first.

Most of the work is the rewriting, because a ticket title describes the work and a release note describes the result. This guide shows that rewrite line by line, then lists what to cut and what you have to include even when it's awkward. At the end, eleven invented tickets become one finished set of notes. To start from a page with the headings already there, copy our free release notes template.

Turn each ticket into a line

Take the ticket and ask what the customer would see if they used the product before and after this change. Write that down. The tickets below are invented.

Ticket titleLine in the release notes
Add bulk archive to project listArchive several projects at once. Select them in the list and choose Archive.
Reindex search on writeNew notes appear in search straight away. They used to take up to ten minutes.
Fix timezone offset in reminder jobReminders go out at the time you set. Some were arriving an hour late.
Migrate images to new storage bucketLeave it out. Nothing changes for the customer.

Four habits do most of the work.

Start with what the customer does or sees. "Archive several projects at once" works because the person reading can picture doing it. "Improved project management capabilities" could describe almost any change.

Describe the bug in a fix. The person who hit the problem should recognise it. "Fixed a bug with reminders" doesn't tell them whether it was their bug, but "some were arriving an hour late" does.

Use a number only if someone measured it. "About twice as fast" needs a before and an after from a real test. If you don't have them, say what changed and leave out the size.

Say where to find it. A new feature gets a short path, such as "Settings, Reminders". One sentence is usually enough. If it needs more, link to a help page.

Keep the selling out of it. The person reading release notes already uses your product and wants to know what's different. Save the excitement for the launch email. If the release has one, the product launch checklist keeps the two apart.

What to leave out, and what you can't

Leave out work that changes nothing a customer can see: refactoring, dependency upgrades, new tests, moved infrastructure, internal ticket numbers. Also leave out fixes to bugs that were introduced and fixed within the same release, since no customer ever had them. Keep a Changelog, a guide by Olivier Lacan, makes the same point about raw development history: "Using commit log diffs as changelogs is a bad idea: they're full of noise."

Always include the changes that are uncomfortable to announce, because those are the ones people need most:

  • anything you removed, even if few people used it
  • anything that now behaves differently, such as a default that changed
  • a change to limits or plans, once it has been announced properly elsewhere
  • anything the customer has to do, such as signing in again or updating an integration
  • a fix for a problem that affected people's data or money, with a plain statement of who was affected

A serious incident needs more than a line. Write the postmortem separately for your team, and in the release notes tell customers what happened to them and what they should check.

If a release was pulled, don't delete its entry. Keep a Changelog says yanked versions should stay listed and marked, so someone running that version can find out why it's gone.

Release notes or a changelog?

People use the two words for much the same thing. Keep a Changelog defines a changelog as "a file which contains a curated, chronologically ordered list of notable changes for each version of a project", which also describes good release notes. The real difference is who reads them, and that decides which headings to use.

For customers using an appFor developers using a library or API
HeadingsNew, Improved, FixedAdded, Changed, Deprecated, Removed, Fixed, Security
LanguageWhat you can do nowWhat changed in the interface
Version schemeWhatever the customer sees in the app, or only a dateOften Semantic Versioning

The six developer headings are Keep a Changelog's. The three customer headings are a common shorter set, and they're what our template uses. A release that removes something from a customer product can add a Removed heading for that release, since burying a removal under Improved misleads people.

Semantic Versioning gives a version number three parts, MAJOR.MINOR.PATCH, and says to increase MAJOR for "incompatible API changes", MINOR when you "add functionality in a backward compatible manner" and PATCH for "backward compatible bug fixes". It's written for software with an API. For an app or website that updates all the time, a plain date in the heading works, and you can drop the numbers altogether if nobody ever sees them.

When to write them

Writing the notes the day before release means reconstructing weeks of work from ticket titles. It's easier to draft a line when each ticket closes, while the person who did the work remembers what changed. One person then edits the lines together before the release so they sound like one voice. Usually that's whoever owns the product.

Before you publish, run through this list:

  1. Try each new feature in the live product, following the path you wrote.
  2. Have the person who built each fix confirm the line describes it correctly.
  3. Check that every number comes from a measurement you can point to.
  4. Give the notes to support before customers see them, so nobody hears about a change from a confused customer.
  5. Move the oldest release into the older section so the page stays short.

Then publish them where people will look. A page with a stable address, linked from inside the product, covers most cases. Keep an email for releases that change how people work.

A filled-in example: eleven tickets, seven lines

The product, the tickets and the release below are invented. A small team makes a scheduling app for dog groomers. This is everything that went into version 3.7.

TicketWhat the ticket saysWhere it went
GRM-301Recurring appointments from the appointment form, every 2, 4, 6 or 8 weeksNew
GRM-305Vaccination expiry date on dog profile, warning on any appointment after that dateNew
GRM-309Calendar query moved to indexed view. Median load 2.4s to 0.9s on accounts with over 500 appointmentsImproved
GRM-312Editable SMS reminder text in Settings, RemindersImproved
GRM-316Duplicate reminder when appointment moved on the same dayFixed
GRM-318Deposit on some PDF receipts rounded down, 1 cent outFixed
GRM-320Client search doesn't match across accents, either way (Muller, Müller)Fixed
GRM-323Upgrade date libraryLeft out
GRM-325Refactor appointment form stateLeft out
GRM-327Crash in recurring appointments, found in testing for this releaseLeft out
GRM-329Move error logging to new providerLeft out

Here is what the customer reads, laid out on the headings of the release notes template.

3.7 · 27 October 2026

New

  • Repeat appointments. Book a dog every 2, 4, 6 or 8 weeks from the appointment form, and each visit goes into the calendar.
  • Vaccination dates. Add the expiry date to a dog's profile. Any appointment after that date shows a warning.

Improved

  • The calendar typically opens in about 0.9 seconds, down from 2.4, for accounts with over 500 appointments
  • Change the wording of your SMS reminders in Settings, Reminders

Fixed

  • Clients got two reminders if you moved their appointment on the same day. They now get one.
  • The deposit on some PDF receipts was 1 cent too low. Receipts now show the correct deposit.
  • Searching for "Muller" now finds "Müller", and the other way round

3.6 · 29 September 2026

New

  • Add a photo to a dog's profile

Fixed

  • The day view now scrolls to the current time when you open it

Older releases (folded away on the page)

  • 3.5: client notes, printable day sheet
  • 3.4: SMS reminders

Set the ticket table beside the finished notes. Every row marked New, Improved or Fixed has its line, and no Left out row does. Customers could never see three of those left-out tickets. GRM-327 looks as if it belongs, because it's a crash, but it only ever existed in testing, since the feature hadn't been released yet.

GRM-309 shows why a ticket should record its numbers. The engineer measured the median load time before and after, so the note can give both figures. Without them, it could only say the calendar opens faster.

The lines for GRM-316 and GRM-318 describe what a customer would have seen, because each bug could have made a groomer look careless. A groomer whose client complained about two text messages can read that line and know it's sorted.

Writing release notes in Prompt Notebook

Prompt Notebook is ours, so read this part with that in mind. The release notes template is a single page with the newest release on top. Each release has a heading with its version number and date, with New, Improved and Fixed underneath, and older versions sit in a toggle at the bottom. The sample inside is for an invented invoicing product.

To draft a line, paste ticket titles onto the page, select them and choose Ask AI. In the box that says "Tell the AI what to do with the selection…", type something like "rewrite each line as what a customer would notice". Check each line afterwards against what actually changed, because the AI only has the ticket title to work from and can make a change sound bigger than it is. When the page is ready, publish it and link to it from your app or website. New releases appear at the same link, so you only ever share one address.

The reasoning behind a feature belongs in its PRD, and customers get the short version in the notes.

Frequently asked questions

What is the difference between release notes and a changelog?

People often use the words for the same thing. Where they differ, a changelog is usually technical and written for developers, and release notes are written for the people using the product. Neither should be a copy of every commit. Pick one page and one audience, then write for them.

What should release notes include?

The version number or date, then what's new, what's improved and what's fixed, each in a sentence the customer can understand. Add anything you removed, anything that now behaves differently and anything the customer has to do. Leave out internal work that changes nothing for them.

How long should release notes be?

As long as the changes that matter to customers, usually one or two sentences per change. A small release might be three lines. Link to a help page for anything that needs real explanation.

Who should write release notes?

The person who owns the product usually edits them, because they know what customers care about. The people who built each change should draft or check their own lines, because they know what actually changed. Support should read them before they go out.

Should release notes list every bug fix?

List the fixes a customer could have noticed. A bug that was introduced and fixed within the same release never reached anyone, so it doesn't need a line, and neither do fixes to internal tools. If you ship a long list of tiny fixes, one line such as "small fixes to the calendar" is honest enough.

Try it on your own notes

Prompt Notebook is free, with unlimited pages. Type one sentence and the AI drafts the first version.

Cookies and storage

Prompt Notebook needs one cookie to keep you signed in. Accepting turns on Google Analytics and Google's reCAPTCHA spam check on the contact form, and declining keeps the form working. Nothing optional runs until you choose.

Read the privacy notice