How to write release notes

Whoever shipped the change drafts all four, with a model doing the first pass. Product approves the customer note and the executive one-pager, and whoever presses release signs the on-call entry. One drafter, two approvers, no committee. Tenhaw runs the same split on client engagements, where the agentic lead owns delivery and decision rights inside the client's own management structure and the client owns all code, documentation and work product from day one. If the drafter is not on the rota, someone who is reads and countersigns the on-call entry before the release date is confirmed, because that is the artefact they will be woken up by.

Then there is no customer note, and saying so is the correct output. Write no customer note required on the ticket so the absence is a recorded decision rather than an oversight. You still owe the on-call entry, because invisible changes are the ones that page people, and support still gets two lines if anything they can see in an admin tool, an export or a log has moved.

You can generate a draft, and you should. What you cannot do is publish it unread. Tenhaw drafts the same way on client work and then verifies every claim by hand against an engineering standard it publishes as open source, 72 rules with RFC 2119 severities on GitHub. Commit messages describe the work, not the change in the customer's day, and they carry service names and ticket IDs that have no business in a customer note. Treat generated text as a first pass to be verified against the evidence folder, and expect to rewrite the customer note almost entirely, because that reader sits furthest from the diff.

Write the on-call entry first and four lines is enough: what changed, the flag, the rollback, the blast radius. The rest follows within one working day. Do not skip the executive line if the fix changes what the epic is expected to be worth, and do not skip the support pack if a customer might notice, because a hotfix support has not been briefed on generates the same tickets a planned release does, at a worse moment.

Before, as part of scheduling the release, not as a tidy-up after it lands. Write the ship kit when a change has been reviewed and product-approved and is about to get a release date, because that is when the person who knows the blast radius is still on the work. Written afterwards, the on-call entry gets reconstructed from the diff by whoever is free, at exactly the moment it is least useful. Budget about three hours for all four artefacts, starting with twenty minutes building an evidence folder: the commit range, the passing test run, screenshots, the flag and the rollback procedure. A missing piece is a readiness problem, and far cheaper to find now than at 3am.

About eighty words in three parts: one sentence on what changed, two or three lines on what to do differently, and where to find it. Write it in the customer's words, and the quickest way to find those is to read the last five support tickets touching this workflow and borrow the language customers actually use, which is rarely the feature name your team argued over. Strip ticket IDs, service names, internal team names and anything about the pipeline that built it. And if the change sits near a workflow people are protective of, name what has not changed, because that is the fear the note has to answer.

A support pack, at least 48 hours before the first cohort, never on the morning of the release. The useful shape is a table rather than a narrative: the symptom in the customer's words, the one-line answer, a ready-to-send macro, and when it escalates, with three rows minimum covering the questions the change will actually generate. Add who is affected and who is not, by plan or cohort, the limitations you shipped on purpose, what a ticket must contain before it comes back to the team, and the signal that means stop widening the rollout. Hearing about a release from a customer costs support more goodwill than the release earned.

The commit range, the feature flag and its current default, any migration and whether it reverses, new configuration and secrets, changed dependencies, and the two dashboards or alerts most likely to move. Write it for a tired stranger. The reader is a developer who was not involved in the change, is half asleep, and has a pager going off. Then the line that matters most: the exact rollback step, how long it takes to bite, and whether it has ever been run against a real environment. If rollback really means a forward fix because a migration is destructive, that fact belongs in the first two lines, not the last. Finish with the blast radius: which cohorts, regions and downstream services.

No. A shipped feature is a claim about work, not about money, and reporting the epic's planned share as banked value kills outcome validation before it runs, because nobody re-examines a number already reported as earned. Tenhaw reports value monthly on its own engagements against the numbers agreed with the client, and a month that moves none of them is reported as a failed month. So the executive one-pager states the epic, the outcome, the planned currency share and what shipped, then the evidence that exists today, the mechanism the value should arrive through, the date of the next monthly outcome validation, and a line reading realised value to date, nil. The epic stays in value monitoring until validation settles it.

The ship kit is everything The Tenhaw Way requires before a release date is agreed: a customer note, a support pack, an executive one-pager and an on-call entry, plus the rollout plan and comms schedule naming who sends each and when, a person's name against every line. Tenhaw publishes The Tenhaw Way in full, seventeen how-to guides included, free to adopt without hiring anyone. The kit exists because one note relabelled four times gets read carefully by nobody, so each artefact is written for its own reader. All four attach to the ticket so the chain holds back to the epic, the outcome and its currency target, and the customer note and support pack then hand into the seven-day live monitoring window.

Say who has it and who does not, in the customer note and again in the support pack. The pack carries a line naming who is affected by plan or cohort, and support needs the negative case in writing, which in the worked example is that legacy-plan accounts cannot see the new setting and must not be promised it. Timing follows the rollout plan rather than the deploy, so the in-app note lands with the cohort that has the change and the public changelog waits until the rollout is wide enough for it to be true. The on-call entry then names the blast radius: which cohorts, which regions, which downstream services.

Split them by reader, then run the test that settles it. Give your last note to someone outside the team and see whether they can say what changed and what to do next. If they cannot, the customer note is the first rewrite, in the words customers use rather than the ones the ticket used. The on-call entry comes next, because written after the event it gets reconstructed from the diff by whoever is free, at the moment it is least useful. Then the support pack, 48 hours before the first cohort. The executive one-pager can wait until the first three are routine. Tenhaw does this repair inside client teams, where a client engineer finished a two-week build 70% confident of running it unaided.

Twenty minutes of collecting, before any prose. Walk up the chain from the ticket to the story, the epic, the outcome and its currency target, and copy out the epic's planned share, because the executive note needs that figure exactly. Then the commit range, the passing test run, the acceptance criteria or key user journeys with evidence they were demonstrated, screenshots of the new state, the flag name and its default, any migration and whether it reverses, and the rollback procedure with the date it was last run against a real environment. The folder is also what you verify the draft against, so strike any claim you cannot point at a file inside it.

Decide before the release. The rollout plan carries the cohorts as percentages with dates, and the named metric and threshold that must hold at each step, so widening is a check rather than a mood. Tenhaw runs client rollouts this way on its engagements, under partner oversight from James Rooney. A plan might start at 5% internal accounts on Tuesday, widen to 25% on Thursday if the send rate the change moves stays within 10% of baseline and no P1 has been raised, then 60% the following week. Every line carries one person's name and a date, never a team name. Support also gets a written signal that means stop widening.

To keep a clean comparison group for when the number is questioned. Hold one cohort, say 10%, at the old behaviour until the seven-day live monitoring check closes. Without it, the only comparison you have is the same population before and after, which moves for a dozen reasons that have nothing to do with your change, and that is exactly what gets picked apart at outcome validation. The held cohort is also a cheap sanity check while the window is open. If a metric looks alarming in both groups, the cause is the week rather than the release.

Then the on-call entry says so, in those words, and the conversation happens before the release date is agreed rather than at 3am. Revert the deploy is not a procedure when the migration is destructive or the flag was deleted in the same release. The entry names the exact rollback step, how long it takes to bite, and the date it was last run against a real environment. If rollback really means a forward fix, that belongs in the first two lines, not the last. In practice, having to write that date is what sends someone to run the step in staging first, which is the point of asking.

Drafting gets easier and verification gets harder. On Tenhaw's own AI-native builds the notes come off the outcome ticket rather than off stories, and the team reading them is two or three senior people, founder-led. An AI-native team has no stories, and the evidence is whatever that ticket already demanded, the test requirements passing and the key user journeys demonstrated working. The catch is that nobody typed the code, so no one carries the blast radius in their head. The on-call entry has to be derived from the diff and the migration files, then read line by line by whoever will be paged. Ask the model to mark every claim it inferred rather than read, and delete those first.