Product Release Notes and Changelog
Release notes get written from the ticket list, which records what engineers did. This register starts by asking what a customer can see.
Free download · No account needed
A release of 143 merged pull requests contains 25 things a customer can observe. The other 118 are driver upgrades, refactors, test coverage, deleted dead code and added tracing: real work, no visible effect. Write the notes from the ticket list and all 143 arrive with equal weight, which is how a page ends up reading "fixed an issue where" nine times. Marking the invisible ones is not busywork. It is the step that makes the remaining list short enough for anyone to finish.
Then the 25 get ranked by how many accounts will notice, and that order disagrees with the one the release was discussed in. Single sign-on with automatic provisioning reaches 64 accounts of 2,180. A queue rewrite filed as internal infrastructure reaches all 2,180, because it took tracking updates from fifteen minutes to ninety seconds, and nobody files a user-facing ticket for that. Reach is a number, so it settles the running-order argument without anyone having to win it.
Anything requiring the customer to act leaves the release note entirely and gets its own message, its own list and a date, ahead of the release. What is left cuts three ways from the same rows: the email, the in-app message and the changelog entry, which cannot contradict each other. Generating notes straight from a commit range is release notes from commits; the launch around one bet is the launch brief pack.
What is in the pack
Change Register
One row per change, carrying the title as merged, whether a customer can observe it, the statement rewritten as what the user can now do, the account reach, and whether it needs a response.
Publication Calendar
Every artifact the register implies, dated and owned, including the deadline rows that carry migration progress. Twelve of two hundred and ten unmigrated four days out is a fact that lives nowhere else.
Release Notes by Audience
The customer email cut to the changes above your reach threshold, plus the segment notes the cuts imply, with each cut rule written down so nobody relitigates it next month.
In-app Announcement
Cut by reachability rather than reach, plus the targeted banner for action-required changes that reappears for admins until the account has actually migrated rather than until somebody clicks dismiss. It also has to fit inside whatever interruption budget the rest of the product is already spending.
Changelog Entry
Every observable change, grouped with removals and breaking changes first, because the reader who needs the page most urgently is the one whose integration just broke.
Writing a User-visible Statement
The method, with worked translations and the banned constructions: fixed an issue where, improved performance with no number, internal component names, and various bug fixes.
How it works
- 1
Send the change set
Merged pull requests, a tag range, a Jira or Linear export, or a spreadsheet. Account counts by plan or flag if you have them.
- 2
Mark what is visible
Observable, indirect, or not. The indirect rows get the most attention, because that is where the biggest change in the release usually hides.
- 3
Rank by reach
Every survivor carries how many accounts will notice, so the running order stops being decided by whoever is most senior in the room.
- 4
Cut three ways
Email by reach, in-app by what the reader can reach from that screen, changelog by nothing. Action-required changes go out ahead with a date.
Frequently asked questions
What do I send it?
Merged pull requests, a git tag range, a Jira or Linear export, a board filtered to Done, or a spreadsheet somebody keeps by hand. Several at once is normal and duplicates get merged into one row with both references kept. Diffs or descriptions help most on the infrastructural changes.
How does it decide a change is invisible?
One test: if nobody wrote it up, would a customer notice something different. A driver upgrade, a refactor and new test coverage all fail it. A queue rewrite that moves an update from fifteen minutes to ninety seconds passes it indirectly, and those are the rows worth the most attention.
Where does the reach percentage come from?
Plan entitlements, feature flag exposure, or the count of accounts that touch the surface involved. Where none of that is available it says unknown rather than estimating, and unknown rows sort to the bottom visibly unranked. A guessed percentage would order the whole release.
Why not put the breaking change in the release note?
Because the people who must act are a small subset of the readers and the note is written for the majority who need not. Both action-required changes in the worked example went to their exact accounts five days ahead of the release, with a date. The release note mentions neither.
How does it handle version numbers and breaking changes?
By whatever scheme you already use, defaulting to semantic versioning and saying so, so somebody can overrule it once instead of every month. Removals lead the changelog, name the old string as well as the new one, and carry their deadline in the line itself. A removal with a migration behind it needs the sunset pack rather than a changelog line.
Can it write for our voice?
Yes, and it reads your last several releases to get it rather than asking you to describe it. What it will not carry over is the constructions the space rule bans, so if your previous notes said fixed an issue where nine times, that specific habit does not survive the migration.
We ship continuously. Is a release even a thing?
The register does not care about release boundaries, only about date ranges. Point it at the last two weeks and the same three artifacts come out. Continuous shipping makes the reach ranking matter more, since without a release moment nothing else imposes an order. Rank the work itself with the prioritization pack.
Find out how much of your release is visible
Send the change set however it exports. The first number back is how many of those changes a customer could notice without being told.
Sort my release