Release notes fail in two directions: never written (the "changelog" is a link to a commit log), or 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, in customer language, on one screen, per release — that takes fifteen minutes a week and quietly closes a category of support tickets.
You can read the full note on the HIVE80lab ops-notes site — here is the working version.
The template: one screen per release
Release 4.12 — 12 Sep 2026 — "exports stop timing out"
BREAKING (first, with a deadline)
- API keys now expire after 365 days. Rotate by 30 Sep: Settings → API.
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)
- Past-due invoices now show a badge in list view; no action needed
NEW
- Saved filters for the customer list
UNDER THE HOOD (optional, one honest line)
- export rendering moved to a queue; should absorb the Friday rush
The rules baked into the format:
- Customer language, not commit language. "Refactor auth middleware" describes your afternoon; SSO logins now survive an expired session describes their week.
- Breaking changes go first, or the format is a lie. Deadline, steps, and a rotation path — an integrator should learn about 401s from you, not from their own error logs.
- Fixed items name the symptom the customer saw. "Exports over 10k rows timing out" is searchable by the person who hit it; "OPS-238" is not.
- Every Changed item answers "what do I need to do?" — even when the answer is "nothing." The missing answer is what generates the support email.
The three readers
Support reads the notes to pre-answer tickets — and links the Fixed entry when closing a matching ticket, which makes the notes the single source of truth instead of a parallel channel.
Integrators scan for API, webhook, and auth changes. The Changed and Breaking sections exist almost entirely for them; if those are unreliable, they stop reading the page and start reading your traffic.
The quiet churner never writes in. For them the cadence is the message: a steady weekly page says alive; a three-month gap says evaluate alternatives. A modest honest note every week beats a quarterly essay.
Cadence and placement
- Every production release gets notes. Shipping daily? A weekly digest assembled as you ship, not reconstructed from memory on Friday.
- Publish where customers already look — app footer, and cross-linked from the status page for anything user-visible. Behind a login nobody has is a diary, not a channel.
- Breaking changes get a long-fuse document too — the API deprecation notice template handles months of warning; the release notes carry the short weekly reminder until the deadline passes.
- The git log is not release notes. The diff says what changed; only a sentence says whether it matters.
The five traps
Commit messages pasted as notes. "chore: bump deps" trains customers that opening release notes wastes a click — and then the breaking-change note arrives to nobody.
Breaking changes last. An API expiry buried under three paragraphs about a new dashboard is a priority statement, and integrators pay for it.
Marketing adjectives. "Blazing fast export improvements" answers none of the three questions. "Exports over 10k rows completed in under a minute now" answers two.
Apologies without dates. "We're working hard on exports" every release for two months is noise. "Fix lands in 4.13 on 3 Oct" is a promise with a timestamp. If there's no date, say what has to be true first.
Notes only for launches. The page going quiet between big releases inverts the aliveness signal exactly when it matters most. Weekly small notes, held.
Worked example
An eleven-person invoicing SaaS ships monthly and announces with a marketing email nobody opens. Support fields a steady drum of "is the export thing fixed yet?" tickets; 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: support links Fixed entries when closing tickets, API-affecting lines carry a tag the partner docs point at, breaking changes run first with deadlines.
Nine weeks later: the "is it fixed" category is down roughly 60% — the answer is now a link. The partner's next adaptation takes one ticket instead of an escalation. Two renewal conversations cite the changelog unprompted as evidence the product is moving. Total cost: fifteen minutes each Friday, in the meeting where the four delivery numbers are already read.
The counter-example is their own previous tool: a JIRA-generated changelog of ticket IDs and links. Customers could not read it without access, so they didn't — and the knowledge that "the product is moving" traveled by rumor or not at all.
From the HIVE80lab kit
- Score your incident response free — 12 questions, tiered fix-first plan
- 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.
Top comments (0)