tinyhumansai Release Notes
Write what changed for the person using the product. Not what was merged, not what the team is proud of.
When to use
- A
releasesrow moves to rolling out. - A customer asks what is new, or what they are running.
Steps
- Read the release row, not the commit log.
contentsis already grouped the way customers experience the change; the commit log is grouped the way the work happened. - Sort by who it affects. Anything that changes existing behaviour comes first, then new capability, then fixes. Something a customer must do comes above all of it, labelled as such.
- Write each line as an outcome. "Exports now include archived records" — not "fixed export filter predicate".
- Name the breaking changes plainly, with what to do about each. A breaking change described gently is one somebody discovers in production.
- Check against the docs. Anything described here that the docs still describe the old way is a doc task, opened now.
- Leave internals out. Service names, ticket numbers and internal codenames mean nothing outside and sometimes mean too much.
Output
Release notes ready to publish, ordered action-required → changed → new → fixed, plus any doc tasks the pass turned up. Publishing is a person's call.