How to write release notes

Write release notes by leading with what changed for the reader, in the reader's words, one item per change, with what they can now do rather than what you did. Group by new, improved and fixed. Name the people who asked when you can. Keep each item to two sentences and link to the place in the product where the change lives.

Release notes are the public record of what changed. They are read by two audiences at once: the customer who asked for the thing, and the customer who never asked and is skimming to see if anything affects them. The template below works for both.

A release notes template you can copy

## [Product] — [Month Day, Year]

### New
- **[Feature name].** [What the reader can now do, one sentence.] [Where to find it.]

### Improved
- **[Area].** [What is faster, clearer or easier, one sentence.] [Why it matters, if not obvious.]

### Fixed
- **[Symptom the customer would recognize].** [What now happens instead.]

### Coming next
- [One line on what is being built now.]

Rules that keep it readable:

• Symptom, not cause. "Invoices from last month now appear in search" beats "fixed a stale index bug."
• Reader's verb. "You can now export a range" beats "we added range export."
• One item, one change. If a bullet has "and" in it, it is two bullets.
• Link in. Every item links to the screen or doc where it lives.

Who writes release notes

The person closest to the customer's words. In most teams that is product, with engineering supplying the list of what merged. In small teams it is the founder. In teams with an AI coding agent in the loop, the first draft can come from the spec that produced the change, because the spec already holds the customer's quote and the exit criteria.

Whoever writes them, the source should be the same: the record of what shipped, with the customer evidence still attached. If the notes are written from memory or from commit messages, the customer's words are gone by the time they are published.

The release note is not the only note

A release note tells everyone. It does not tell the customer who asked that their request is the third bullet. Those are two different messages.

The second one is a shipped notification: a note to a specific customer that the feature they asked for is now available, quoting what they said. It is what closes the loop. It should go out alongside the release note, not instead of it.

Annsa sends it from the spec. Mark the spec Shipped and Share Back lists every customer who asked, with their email and original quote. Add a note of up to 300 characters or leave the default, and approve once. The email carries the customer's own words, a short line on what was built, and a question, "Did this solve it for you?", with Yes and Not yet buttons. Templates for that message are in email templates for telling a customer their feedback shipped.

A worked example

From a spec whose Customer Voice section reads "I can never find last month's invoice, search only seems to look at this month":

### Improved
- **Search now covers all billing history.** Searching for an invoice
  returns results from any month, not only the current one. Open
  Billing → Search.

And the shipped notification to the customer who said it:

You mentioned that search only seemed to look at this month's invoices. That's fixed: search now covers your whole billing history. Did this solve it for you?

Same change, two messages, two readers.

Before you publish

• Every item names something the reader can do or see
• No item describes internal work
• Every item links somewhere
• The customers who asked are getting their own note
• The date is on it

The last one matters more than it looks. Undated release notes cannot be cited, and cannot be compared with the last set.