How to write release notes

Build the evidence folder before you write

Twenty minutes, one folder, no prose yet.

Walk up the chain from the ticket: story, epic, outcome, currency target, and copy out the epic's planned share, which the executive note needs exactly. Then collect 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. A missing piece is a readiness problem, not a writing problem, and cheaper to find now than at 3am.

Write the customer note in the customer's words

Eighty words, three parts: one sentence on what changed, two or three lines on what to do differently, and where to find it.

First read the last five support tickets touching this workflow and steal the words customers use, because they will not be the feature name your team argued over. Strip ticket IDs, service names, internal team names and anything about the pipeline that built it. 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. If the change is invisible to users, write no note and record that decision on the ticket.

Write the support pack as answers, not narrative

Build a four-column table: the symptom in the customer's words, the one-line answer, the ready-to-send macro, and when it escalates.

Three rows minimum, covering the questions this change will generate, not the ones you wish it would. Add who is affected and who is not, by plan or cohort, and the limitations you shipped on purpose. Then the two lines that save the most time: what a ticket must contain before it returns to the team, and the signal that means stop widening the rollout. Support gets this 48 hours before the first cohort, not on the morning. Hearing about a release from a customer costs more goodwill than the release earned.

Write the executive one-pager against the number

One page, four lines: the epic, the outcome it rolls up to, the epic's planned currency share, and what shipped in plain English.

Then the honest part, in three more: the evidence that exists today, the value expected and through what mechanism, and the date of the next monthly outcome validation, when this number first gets tested. Add a line reading realised value to date, nil. Do not claim delivered value. The epic sits in value monitoring until validation confirms the number or someone closes it saying the value did not land. Reporting a shipped feature as banked value is the one sentence that breaks the loop.

Write the on-call entry for a tired stranger

This is the developer changelog in the ship kit.

Its reader was not involved, is half asleep, and has a pager going off. Name the commit range, the 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. Then the line that matters: the exact rollback step, how long it takes to bite, and whether it has ever been run against a real environment. If rollback means a forward fix because a migration is destructive, put that in the first two lines. Finish with blast radius: which cohorts, which regions, which downstream services.

Attach the rollout plan and comms schedule

The notes are useless until someone has agreed when each lands.

Write the cohorts as percentages with dates: who gets it first, how long you hold before widening, and the named metric and threshold that must hold at each step, so widening is a check rather than a mood. Then the comms: who sends the customer note and when, who briefs support, who posts internally, and whether anything goes to a public changelog. A person's name against every line, never a team name. Hold one cohort at the old behaviour until the seven-day live monitoring check closes, so you keep a clean comparison group for when the number is questioned.

Draft with AI, then verify claim by claim

This is one of the places AI earns its keep.

Hand a model the diff, the ticket, the test output and the demonstrated journeys, and ask for all four artefacts in one pass, each written for its own reader, marking anything it inferred rather than read. Then go line by line and strike every factual claim you cannot point at a specific file in the evidence folder. Models write confident notes about behaviour nobody implemented, and a model reporting that it has finished is not evidence that it has. Product approves the customer note and the one-pager; whoever presses release signs the on-call entry.

Publish, link back, hand into live monitoring

Attach all four artefacts to the ticket so the chain holds: anyone opening it reaches the notes, the epic, the outcome and the number behind it. Publish on the schedule, in the order you wrote. Then hand the customer note and the support pack into live monitoring, because for seven days they are what you triage against: the FAQ gets extended as real questions arrive, the macro gets corrected where it was wrong, and the continue, watch or rollback call is made against thresholds you already agreed rather than invented under pressure. When live monitoring closes, the epic stays in value monitoring until outcome validation reports.