vstorm-co Writing release notes
The reader wants to know whether anything they use has changed. Sort for that.
Group by consequence
Breaking first, always, with what to do about it · then new capability · then fixes, described by the symptom the reader saw rather than the code that changed · then internal, briefly or not at all.
Write from the outside
"Uploads over 10 MB failed silently" tells a user whether it affected them. "Fixed a race in the ingestion worker" does not.
Breaking changes
State what breaks, what to do, and by when. If a migration is needed, link it. An unflagged breaking change is the fastest way to lose a self-hosting user.
Always include
The version, the date, and the issue or PR number for anything a reader may need to chase.
Never
List every commit, use the commit subject as the note, or hide a behaviour change under "improvements".