Release notes for users, developers and your boss

When a team ships often, the same release has to answer three different questions: what can I do now, what breaks, and what do I tell the customer. Writing one list of changes for all three means two of the three stop reading. This guide shows how to write the facts once and answer each question separately, with before and after examples.

Why one list fails

People who ask how others handle this describe the same three habits: pasting raw GitHub release text into customer emails, rewriting the same update by hand for each audience, or skipping release notes because both are too much work. In a Hacker News thread from December 2025 on exactly this question, one reply argued that nobody reads them so one version is enough, and another that generated changelogs lack the business context about which change matters. Both are right about the failure: a list built from commits answers the developer's question and nobody else's.

Three readers, three questions

One change, three versions

The commit message was perf: paginate board cards, default 100. Here is what each reader should get.

• Developers: GET /v1/boards/{id}/cards returns 100 cards per page (limit up to 250) and a next_cursor. Scripts that assumed every card comes back in one response must follow next_cursor.
• Users: Boards with hundreds of cards open about three times faster. (Only say a number you measured.)
• Team: Performance work for the three biggest customers is done; their open tickets can be closed.

The developer line is the source of truth. The user line drops every word that needs the API to understand it. The team line turns the same fact into an action.

A ten-minute routine

1. Write the one-sentence summary first. A user reading a list should know from it whether to care.
2. Write the developers section in the order a reader hits the changes: breaking changes first, each with the replacement.
3. For users, keep only what a person using the product could notice. A patch release that fixes an internal problem has no user section, and that is fine.
4. For the team, write what to do or say. If nobody has to act, say so or leave the section out.
5. Read each section as the person who will receive it. Cut anything they would have to look up.

Words that give you away

If the users section says refactor, dependency, endpoint, payload, migration or pull request, it was copied from the developer notes. Say what changed for the person: instead of "refactored the importer", write "Importing a CSV no longer stops on files saved by Excel". Name the place in the product ("in Settings > Notifications") rather than the module.

Breaking changes and security notes

A breaking change needs four things: what changed, since which version it was deprecated, what to use instead, and when the old way stops. A before and after code block is worth a paragraph. For a security fix, tell readers what to do first (update, rotate a token, check a list), then what was wrong, in the least detail that lets them judge the risk. Do not publish exploit steps in the release that fixes the problem, and do not write "no evidence of misuse" unless you looked.

Where to keep them

Keeping each release as a short text file in the same repository as the code makes the notes reviewable like code, and lets a build turn them into pages and feeds. The Release Notes Kit does that: one Markdown file per release, a history page and an Atom and JSON feed for each audience, and a checker that stops the build on a typo. If you would rather paste into a document, the habits above are the part that matters. You can try the wording checks on your own notes with the free release notes checker.

Sources

Ask HN: How do you handle release notes for multiple audiences? (news.ycombinator.com/item?id=46257486, 13 December 2025). Keep a Changelog 1.1.0 (keepachangelog.com/en/1.1.0) for the six standard change types. The before and after examples are invented.