Release notes for small teams: the template customers actually read

Release notes fail in two directions: they are never written (the "changelog" is a link to a commit log), or they are written as marketing — adjectives where facts should be. Customers open release notes for exactly three reasons: is the thing I reported fixed, is anything about to change under me, and is this product still alive? A template that answers those three questions, in customer language, on one screen, per release — that is the whole discipline. It takes fifteen minutes a week and quietly closes a support ticket category.

This note gives the template, the three readers you are actually writing for, the cadence rules, the five traps that turn release notes into wallpaper, and a one-afternoon rollout.

1. The template: one screen per release

Release 4.12 — 12 Sep 2026 — "exports stop timing out"

BREAKING (if non-empty, this goes first, with a deadline)
- API keys now expire after 365 days. Rotate by 30 Sep: Settings → API.
  Integrations that don't rotate will start receiving 401s on 1 Oct.

FIXED
- CSV exports over 10k rows no longer time out (reported by 6 teams)
- Timezone display in the audit log now matches the viewer's profile

CHANGED (what behaves differently + what you must do, if anything)
- Invoices past due now show a badge in list view; no action needed

NEW
- Saved filters for the customer list

UNDER THE HOOD (optional, one honest line)
- moved export rendering to a queue; should absorb Friday spikes

The rules baked into the format:

• Customer language, not commit language. "Refactor auth middleware" describes your afternoon; logins from SSO now survive an expired session describes their week. If a line would make sense only to someone with repo access, it is a commit message, not a note.
• Breaking changes go first or the format is a lie. A breaking change buried under “New” is how integrators learn about 401s from their own monitoring. Deadline, steps, and a contact, at the top.
• Fixed items name the symptom the customer saw, not the ticket ID. CSV exports over 10k rows timing out is searchable by the person who hit it; OPS-2381 is not.
• Every Changed item answers “what do I need to do?” — even when the answer is “nothing.” The absence of an answer is what makes people email support.
• One screen, weekly. A notes page that scrolls for six screens is a changelog nobody opens. Weekly cadence forces the discipline that makes each release readable.

2. The three readers

Write for the people who actually open the page:

• Support reads release notes to pre-answer tickets. When a fix lands, support links the note in their reply — which closes the loop and makes the notes the single source of truth instead of a parallel channel. (This is the same loop that keeps an incident status page honest: one public place, kept current.)
• Integrators scan for anything that touches the API, webhooks, or auth — the Changed and Breaking sections exist almost entirely for them. If those sections are unreliable, they stop trusting the page and start testing everything in staging, and you pay for that in their adoption speed.
• The quiet churner never writes in. For them the notes are a pulse: a steady weekly page says alive; a three-month gap says evaluate alternatives. The cadence communicates even when the content is modest — which is also why the maintenance-window announcement shares this page's format: scheduled or shipped, it is the same promise of “we tell you before we touch your workday.”

3. Cadence and placement

• Every production release gets notes. For teams shipping daily, that can be a weekly digest — but the digest is assembled as it ships, not reconstructed from memory on Friday.
• Published where customers already look: linked from the app footer and, for the ones that matter, the status page. A notes page behind a login nobody has is a diary, not a channel.
• Breaking changes get their own fuse: the deprecation notice template handles the long-fuse cases (months of warning, direct emails); the release notes carry the short reminder (“expires 30 Sep, rotate now”) every release until the deadline passes.
• The git log is not release notes. The diff tells you what changed; only a human sentence tells anyone whether it matters. The fifteen minutes of writing is the work.

4. The five traps

Commit messages pasted as notes. “refactor auth middleware,” “chore: bump deps,” “fix tests” — a page of these trains customers that opening release notes is a waste of a click, and once that training lands, the breaking-change note arrives to an empty room.

Breaking changes last. Order is a claim about priority. If the API expiry notice sits under three paragraphs about a new dashboard, the format says we are proud of the dashboard, and the integrator pays for the sentence.

Marketing adjectives. “Blazing fast improvements to exports” answers none of the three questions. Speed claims need the symptom and the number: exports over 10k rows were timing out; they complete in under a minute now.

Apologies without dates. “We're working hard on the export issues” in every release for two months is worse than one line: known issue, fix scheduled for 4.13, 3 Oct. A date with a slip beats a promise with none — and if there is no date, say what has to be true first.

Notes only for launches. If the page goes quiet between big releases, the aliveness signal inverts exactly when it matters most. Weekly small notes are cheaper and read more than quarterly essays; the discipline is the same one that keeps a weekly review alive — small, repeated, honest.

5. Worked example

An eleven-person invoicing SaaS ships monthly and announces releases with a marketing email nobody opens. Support fields a steady drum of “is the export thing fixed yet?” tickets, and an integration partner discovers a rate-limit change from their own 401s.

They switch to weekly one-screen notes in the format above, linked from the app footer, with the three readers in mind: support links the Fixed entries when closing tickets, API-affecting lines carry a tag the partner documentation points at, and the breaking-change block runs first with a deadline. Nine weeks later: the “is it fixed” ticket category drops by roughly 60% — the answer is now a link — the partner's integrations survive the next behavior change with one ticket instead of an escalation, and two renewal conversations cite the changelog unprompted as evidence the product is moving. The total cost is fifteen minutes per Friday, pulled from the same meeting where the four delivery numbers are already read. The counter-example is their own previous practice: a JIRA-generated changelog of ticket IDs and links that required access to JIRA to read, which is to say, customers read none of it and support answered all of it.

6. Metrics (for the metric itself)

• 100% of production releases have notes within 24 hours of shipping — the release checklist's last item.
• Breaking changes appear first, every time, with a migration deadline and steps.
• Support links the Fixed entry when closing a matching ticket; the link count is the honest readership metric.
• Weekly cadence held — including the dull weeks. A quiet page teaches customers not to look.
• One screen per release; if a week needs two screens, the week shipped too much unannounced change.

From the HIVE80lab kit

• The First 30 Minutes — free incident quick-start
• Ops Starter Kit — incident response for small teams — $14
• Ops Starter Kit Vol. 2 — advanced incident response & communications — $27
• Ops Mega Bundle — all 5 kits in one download — $49

Related: the API deprecation notice template is the long-fuse version of a breaking change, the maintenance-window announcement covers the planned disruption, and the status page template covers the unplanned one, and the release checklist for small teams is the twelve boxes between a green build and shipped