Release notes examples are the fastest way to learn the form: read three good ones and the pattern is obvious. Release notes are the announcement for one release — what changed, why it matters to the people using the software, and what, if anything, they need to do about it. Every good example has the same three things: a clear version and date, changes grouped by type, and breaking-change or upgrade guidance near the top. This post gives you the standard release notes format section by section, a release notes template you can copy, three worked examples (a SaaS product, an API, and a deployment), one real example generated from a week of commits, and a checklist for how to write release notes without dreading them.
The standard release notes format
Most release notes, from a mobile app to a database engine, follow the same skeleton. Only the depth varies.
| Section | What goes in it | Optional? |
|---|---|---|
| Title and version | Product name, version or release name, and one line that says what the release is about. | No |
| Date | When it shipped (or ships). A full date, not "this week". | No |
| Summary | Two or three sentences: the headline change and who benefits. | No |
| Breaking changes and deprecations | Anything that stops working, or will. Near the top, not at the end. | Only when there are none |
| New | Features that didn't exist before — benefit first, one bullet each. | No |
| Improved | Existing behaviour that got better: faster, clearer, more reliable. | Yes |
| Fixed | Bugs, stated as what now works. | Yes |
| Upgrade steps | Exactly what to run or click to move to this version. | Yes |
| Known issues | What you already know is wrong, so nobody has to report it twice. | Yes |
| Links | Docs, migration guide, full changelog, support. | Yes |
Two conventions are worth knowing. Keep a Changelog standardises the grouping for the running changelog form (Added, Changed, Deprecated, Removed, Fixed, Security), and Semantic Versioning lets readers tell from the version number alone whether to expect breaking changes. Release notes borrow both and add prose.
A release notes template you can copy
# {Product} {version} — {one-line headline}
Released {Month D, YYYY}
{Two or three sentences: what this release is about and who it helps.}
## Breaking changes
- {What no longer works, and what to do instead.}
## New
- **{Feature name}** — {what it lets the user do, in one sentence}.
## Improved
- {What got faster, clearer, or more reliable — and by how much, if you can say.}
## Fixed
- {What now works, described from the user's side.}
## Upgrade
{The exact command or steps. Link the migration guide if there is one.}
## Known issues
- {Anything you already know is wrong, with a workaround.}
Full changelog: {link} · Docs: {link} · Questions: {support link}
Drop the sections you don't need for a given release and keep the order. A software release notes template like this works for a SaaS app, a CLI, or a library, because the reader's questions are always the same: what changed, does it affect me, what do I do.
Three release notes examples
These are sample release notes for software, written for fictional products so that the format is the point rather than the vendor. Each follows the template above.
SaaS product release notes example
A sample release for a fictional invoicing app, written for its customers.
# Ledgerly 4.2 — Recurring invoices and a faster dashboard
Released March 12, 2026
This release adds recurring invoices, the most-requested feature of the year, and roughly halves dashboard load time for accounts with more than a thousand invoices.
## New
- **Recurring invoices** — set a schedule once and Ledgerly issues, sends and reconciles each invoice automatically. Pause or edit a series at any time from the Invoices tab.
- **Payment reminders** — choose reminder days per customer; reminders stop the moment an invoice is paid.
## Improved
- The dashboard now loads in under a second for large accounts (previously two to three seconds).
- CSV exports include the customer's tax ID.
## Fixed
- Draft invoices no longer appear in the overdue total.
- The "mark as paid" shortcut works on the mobile layout again.
Docs: ledgerly.example/docs/recurring · Questions: [email protected]
What makes this a good example: the summary answers "why should I care" before the list, every bullet leads with the user's outcome rather than the implementation, and fixes are stated as what now works.
API / library release notes example
A sample release for a fictional HTTP client library, written for developers. Version numbers carry meaning here, so the breaking change comes first.
# fetchkit 3.0.0
Released June 2, 2026
Version 3 drops Node 16 support and replaces the retry options. Everything else is additive.
## Breaking changes
- Node 16 is no longer supported. Node 18 or later is required.
- The retries and retryDelay options are replaced by a single retry object:
before: fetchkit(url, { retries: 3, retryDelay: 500 })
after: fetchkit(url, { retry: { attempts: 3, delayMs: 500 } })
## New
- **Per-request timeouts** — pass timeoutMs to any request; the promise rejects with a TimeoutError.
- **Typed JSON helpers** — response.json() is generic in TypeScript.
## Deprecated
- fetchkit.legacyAgent still works in 3.x and will be removed in 4.0.
## Fixed
- Redirects to a different origin no longer forward the Authorization header.
## Upgrade
npm install fetchkit@3, then replace retries/retryDelay as shown above.
Full changelog: fetchkit.example/changelog
Deployment release notes template
The internal version — what operations and support read. A deployment release notes template adds the operational facts a customer-facing note leaves out.
# Deployment: checkout-service 2026.09.04
Environment: production (eu-west-1)
Deploy window: Thu Sep 4, 2026, 09:00–09:30 UTC
Owner: {name} · On call: {name}
Rollback: redeploy tag 2026.08.28 (tested in staging Sep 3)
## What ships
- Idempotency keys on POST /orders (new)
- Payment retry backoff raised from 3 to 5 attempts (improved)
- Duplicate confirmation emails on network retry (fixed)
## Customer-visible?
Yes — duplicate emails stop. No UI changes.
## Migrations
One additive migration (orders.idempotency_key, nullable). No downtime.
## Verification
- Error rate on /orders below 0.1% for 30 minutes after deploy
- Zero duplicate confirmation emails in the mail log
## Known issues
- None open.
A real, generated release notes example
The three above are fictional. This one is real: the Shipstar changelog for Aug 28 – Sep 4, 2026, generated by Shipstar itself from 32 commits and published without anyone drafting it. The entry has four New, three Improved and one Fixed item; here are two of them, quoted as published.
New — X threads and Slack updates are now posted automatically on approval. Approving a scheduled X thread or Slack product update now publishes it directly to the destination — no extra manual step required.
Improved — Scheduled content windows now match your chosen cadence. Daily, weekday, and weekly schedules now look back only as far as their cadence — a daily run covers one day, a weekly run covers one week.
It follows the same format as the template — grouped by type, benefit first, fixes as what now works — because that is what the generator is instructed to produce. The provenance line under the heading ("Generated by Shipstar from 32 commits") is the real count, published with every period.
How to write release notes: a checklist
- Lead with the user's benefit, not the ticket. "Invoices send themselves on a schedule" beats "Added cron-based invoice job".
- Group by type — New, Improved, Fixed — so a reader can skip to what they care about.
- Put breaking changes first and say what to do instead, with the exact command or setting.
- Date and version every release. "Last week" means nothing a year later.
- State fixes as what now works, not as a confession about how long something was broken.
- One sentence per bullet. If it needs more, it needs a docs page — link it.
- Keep one voice across releases; readers notice when the tone changes with the author.
- Publish where your users already look — a page on your domain, email for the people who opted in, Slack for the team — not only in a Git tag.
- Keep the archive. A permalink per release lets support link to the note that answers a question.
- Generate the first draft from the code if you can; the commits and pull requests already contain the facts.
Release notes vs. changelog
A changelog is the running record: every change, grouped by version or period, accumulating over time. Release notes are the announcement for one release, written to be read once. Both come from the same commits and pull requests, and most teams need both — the changelog as the durable reference on their site, the release notes as the email, post or GitHub Release that points to it. If the changelog is your bottleneck, the changelog management tool page covers that side; if you ship from GitHub and wonder whether GitHub Releases alone is enough, read GitHub Releases vs. a changelog tool.
Can you provide an example of a change log?
Yes. Here is a changelog entry in the Keep a Changelog style, for the same fictional invoicing release as the first example:
## [4.2.0] - 2026-03-12
### Added
- Recurring invoices with pause/edit per series
- Per-customer payment reminder days
### Changed
- Dashboard load time roughly halved for accounts with 1,000+ invoices
- CSV export includes the customer tax ID
### Fixed
- Draft invoices excluded from the overdue total
- "Mark as paid" shortcut restored on mobile
Compare it with the release notes example above for the same release: the same facts, no prose, no summary. The changelog is the ledger; the release notes are the letter. For a real, continuously updated one, see Shipstar's own changelog.
Generate release notes instead of writing them
Everything in the template is already in your repository: the commits say what changed and the pull request descriptions say why. Shipstar reads the commits and merged pull requests in a GitHub repository for a release window, drafts release notes in this format in your project's configured voice, holds them in a review queue, and on approval publishes them to a hosted page and embed widget and emails your mailing lists (up to 20 lists per project, 500 active recipients each, one-click unsubscribe on every message). It is the automated release notes generator behind the real example above; the release notes software page covers the whole workflow and the release notes newsletter page covers email delivery. The Free plan is $0 with no card — one project and 1,000 credits a month, and a release-notes generation costs 100 credits, so about ten a month are free. Solo is $25/month or $240/year. Connect a repository and compare the generated draft with the template.