Release notes templates: copy-paste formats for every kind of change

The fastest way to write release notes nobody complains about is to stop composing them from scratch. Each kind of change answers the same reader questions every time, so each kind of change can have a template. This page collects seven you can copy today, with notes on when to use each and how to fill it in without producing filler.

How to use a template without sounding like one

A template is a checklist of reader questions, not a mad-lib. Two rules keep the output human:

  • Delete sections that don't apply. A fix with no action required doesn't need a "What you need to do" heading saying "Nothing." Empty sections filled with placeholder prose are how template rot starts — readers learn to skim past the structure, and then past the notes entirely.
  • The blanks are the work. The template guarantees you don't forget the migration path; it can't phrase the migration path for you. Budget two minutes of actual writing per entry — the structure just makes those minutes count.

Every template below assumes the basics from how to write a changelog: a date, a one-line outcome-first title, a tag (new / improved / fix / announcement), and past tense — a changelog is a record, not a roadmap.

1. Feature launch

Use when something new exists. The reader question: "what can I do now that I couldn't yesterday, and where do I find it?"

[new] {What it lets the user do, verb first}

{One sentence: the problem this solves, in the user's words.}

- Where: {menu / URL / flag / endpoint where they'll find it}
- Works with: {plans, platforms, or limits, if any}
- Docs: {link}

{Optional: one honest caveat — "CSV import caps at 10k rows for now."}

Filled in:

[new] Schedule posts to publish later

Write the announcement when the work merges, not when the release ships.

- Where: the "Publish at" field on any draft, or --at on the CLI
- Works with: web, API, and CLI; times are UTC unless you give an offset
- Docs: /docs#scheduling

The caveat line is optional but earns trust out of proportion to its size — naming the limit yourself beats a user discovering it.

2. Bug fix

The reader question: "was that weird thing I saw your bug, and is it gone?" Name the symptom, not the cause — users searched for the symptom.

[fix] {The symptom, as the user experienced it} — fixed

{Who was affected and when it started, if you know.}
{What's true now. If data needs repair, say exactly what to do.}

Filled in:

[fix] Getting signed out when your laptop slept — fixed

Affected everyone on sessions created after July 2. Sessions now survive
sleep; you'll need to sign in once more for the fix to apply.

Resist writing the diff ("fixed race condition in session refresh"). The non-technical readers guide covers this translation in depth.

3. Breaking change / deprecation

The one template where more structure is always right, because the reader question is urgent: "will this break me, and what must I do by when?"

[announcement] Breaking: {what stops working}, on {date}

Who's affected: {precise — "anyone calling GET /v1/export"}
What breaks: {the exact old behavior that ends}
What to do: {the migration, as commands or steps, not prose}
Deadline: {date}. After this, {exact consequence}.
Why: {one honest sentence — optional but disarming}

Announce it three times (announcement, reminder, change day) and never move a published date earlier — the full playbook is in announcing breaking changes. For API audiences, pair the post with in-band signals (Deprecation / Sunset headers) per the API changelog guide.

4. Security fix

The exception to "cut what doesn't apply": every line here is load-bearing, and vagueness reads as cover-up. Say what class of issue, who could have been affected, and what users should do — even when the answer is "nothing".

[fix] Security: {class of issue} in {component} — patched

Impact: {who could have been affected, under what conditions}
Status: {patched as of version/date; whether it was exploited, if known}
Action: {rotate keys / update to vX / nothing required — be explicit}
Credit: {reporter, if they want it}. Details: {advisory link, or "to follow"}

If you run coordinated disclosure, it's fine for details to lag the patch — but the entry itself shouldn't. A dated "we patched X, no action required" beats silence followed by a surprise advisory.

5. App store "What's New"

Constraint-driven: Android truncates around 500 characters, iOS shows a line or two before "more". Lead with the single best change; keep an honest evergreen block only if you actually ship fixes every release.

{The one change most users will notice, one line, plainest words}

Also in this update:
• {second change, if it earns the space}
• {third, at most}

As always: bug fixes and speed-ups. Full changelog: {short URL}

The full-changelog link solves the platform's edit problem — store text is hard to amend after release, a web page isn't. Details and platform limits in app store release notes.

6. API change

Developers scan API changelogs defensively. Answer the five questions in a fixed order so regulars can stop reading the moment one answer clears them:

[{new|improved|fix|announcement}] {endpoint or area}: {what changed}

Breaking: {yes/no — first, always, even when no}
Affected: {endpoints / versions / SDKs}
Behavior: {old → new, concretely}
Action: {what integrators must change, or "none"}
Timeline: {live now | dated rollout | sunset date}

"Breaking: no" as a standing first line lets 90% of readers relax after four words — that predictability is the whole value. More patterns (additive-but-breaking traps, dated versions, machine-readable feeds) in the API changelog guide.

7. Digest (weekly/monthly roundup)

For a stream of small ships — or an internal changelog — batch entries into a dated digest. The template is a shape, not sentences:

{Month D} — {the headline change, as the title}

{2–3 sentences on the headline: what it does, who asked for it.}

Also shipped:
• [improved] {one-liner}
• [fix] {symptom} — fixed
• [fix] {symptom} — fixed

Heads-up: {any dated future change, with its deadline}

One headline, bullets for the rest, heads-ups always last and always dated. If the digest also goes out by email, the same structure survives the trip — see product update emails for when email is the right channel at all.

A CHANGELOG.md skeleton

Maintaining a file in the repo instead (or as well — see open source changelogs)? The Keep a Changelog format is the standard; here's the minimal correct skeleton:

# Changelog

## [Unreleased]

## [1.4.0] - 2026-07-27
### Added
- Scheduled publishing via publish_at
### Fixed
- Sessions no longer die when the laptop sleeps

## [1.3.2] - 2026-07-19
### Security
- Patched header injection in the RSS renderer

Categories only when they apply, newest first, dates in ISO. If you version with dates instead of semver, that's fine — CalVer vs SemVer covers the trade.

Filling any template fast: the four questions

Whatever the shape, every entry is done when it answers:

  • What changed? — in the user's vocabulary, not the codebase's.
  • Who cares? — if the honest answer is "nobody outside the team", it goes in the internal stream or nowhere.
  • What do they do about it? — action, or explicitly none.
  • When? — the date it shipped; a deadline if one exists.

If a section of a template doesn't map to one of those questions for this particular change, cut it. That's the difference between a template and a form.

Where Wakelog fits

Wakelog is a free hosted changelog that these templates drop straight into: entries take a title, a tag (new / improved / fix / announcement), and a markdown body — exactly the fields above. Post from the web, from CI with one curl, or with the CLI (wakelog post --from-git drafts the bullet list for you); schedule breaking-change reminders with --at; and your page comes with RSS, an embeddable widget, and a changelog.md export so the skeleton above is one GET request away.

Start your changelog free   Next: how to write a changelog →

Related guides

Last updated 2026-07-27 · All guides