Release notes

Release notes are read by someone deciding whether to upgrade, and by someone whose upgrade just broke. Write for both — the second one is in a worse mood and needs more from you.

A changelog generated from commit subjects is not a changelog. It is a commit log with a different filename, and it fails the only test that matters: can a reader tell whether this release affects them?

1. Lead with what breaks

Breaking changes go first, always, regardless of how minor they seem next to the exciting feature. Someone scanning for "will this break me" must not have to read past the first section.

For each one:

• What changed, concretely
• What breaks: the symptom they will see
• Exactly what to do, with before-and-after code