Release Notes Template (With 6 Real Examples)

The template

Copy this. Delete any section that has nothing in it; an empty heading is worse than a missing one.

# v2.4.0 - 20 September 2026

Scheduling now handles recurring appointments, and the CSV export
no longer times out on large accounts.

## New

- **Recurring appointments.** Set a weekly, fortnightly or monthly
  repeat when creating an appointment. Existing appointments are
  unaffected.

## Improved

- CSV export now streams, so accounts with more than 50,000 rows
  export without timing out. Previously capped at about 20,000.
- Search results return roughly twice as fast.

## Fixed

- Timezone was wrong on appointment reminders for users in UTC+13.
- Deleting a client left their appointments visible in the calendar.

## Breaking

- The `/v1/appointments` endpoint now returns `startsAt` in ISO 8601
  instead of a Unix timestamp. `/v0` is unchanged and supported
  until 1 March 2027. [Migration guide](#)

## Known issues

- Recurring appointments cannot yet be edited as a series. Editing
  one occurrence edits only that occurrence. Fix expected in 2.5.

The six sections, and when to drop each

The summary line

One or two sentences at the top answering "what is the most important thing that changed?" Never drop this. Most readers read only this, and a release note without it forces everyone to reconstruct the headline from a bullet list.

Write it last, after the bullets, when you can see what the release actually was.

New

Things that did not exist before. Drop it when there are none, which is most releases and is fine. Bold the feature name so it is scannable, then one sentence on what it does and one on anything surprising about its scope.

Improved

Things that existed and are now better. The section most teams write badly, because "improved performance" tells the reader nothing. Give the before and after: twenty thousand rows to fifty thousand, two seconds to one. A number makes it credible and makes it matter.

Fixed

Describe the symptom the user experienced, not the cause you found. "Timezone was wrong on reminders for users in UTC+13" lets someone recognise their own bug report. "Fixed off-by-one in the DST offset calculation" does not.

Drop internal fixes nobody outside the team could have noticed. A changelog of forty entries where thirty-eight are invisible trains people to stop reading.

Breaking

Never drop this when it applies, and never bury it at the bottom of a long list. State what changed, what the old behaviour was, when the old behaviour stops working, and link the migration path. A deprecation date is the part people actually need.

If your release has breaking changes, consider moving this section directly under the summary. Ordering by severity beats ordering by convention.

Known issues

The most skipped section and the one that buys the most trust. Shipping a feature with a stated limitation reads as confidence. Shipping it and letting users discover the limitation reads as carelessness, and generates support load you could have prevented with two lines.

Six real examples, and what each does differently

Linear

Weekly, image-heavy, and linked from the primary site navigation rather than buried in a footer. Entries are short: one to three features plus a small-fixes roundup. The notable choice is treating the changelog as a marketing surface rather than a support document, which is why it sits in the nav.

Stripe

Organised around API versions rather than dates, because for an API the version is the thing a developer needs to pin against. Breaking changes are explicit and dated. Worth copying if you ship an API; worth ignoring if you ship a web app.

Shopify

Segmented by audience: merchants, developers, partners. A single release genuinely means different things to those three groups, and the segmentation means nobody wades through entries that cannot affect them. The right pattern if you have two or more distinct user types.

Vercel

Every entry attributes the engineer or team who shipped it. Small thing, real effect: it makes the changelog read as written by people rather than generated, and internally it is a visible credit mechanism.

Tailwind CSS

Long-form, opinionated release posts that explain the reasoning behind changes rather than just listing them. Expensive to write and only worth it if your users are building on top of your decisions and need to understand them.

GitHub

Every entry links to relevant documentation, so the changelog is an index into the docs rather than a terminus. If you have documentation, this is the highest-value habit on this list and the cheapest to adopt.

Release notes vs changelog

Used interchangeably, and worth separating.

A changelog is the complete chronological record of changes, written for people who need to know exactly what happened: developers integrating against you, support staff diagnosing a report, you in eight months. Completeness is the requirement.

Release notes are a communication, written for users who need to know what changed for them. Selectivity is the requirement, and a release note that includes every commit has failed at its only job.

Small teams can maintain one document serving both, and most should, but write it as release notes and keep the raw list in your version control history where it belongs. See the changelog template for the other format.

Getting them written at all

The template is not the hard part. The hard part is that release notes get written on the day of the release by whoever has least to do, from a Git log, under time pressure, which is why they so often read like a Git log.

The fix is to capture the user-facing description when the work is done rather than when the release ships. One sentence per item, written by the person who built it, while they still remember what it was for.

FlowBoard generates release notes from the work items in a release, which means the assembly step disappears and the only remaining task is editing. See release notes as a status meeting replacement for the argument that this can replace a recurring meeting entirely.