Writing Release Notes

Overview

The default failure is a pasted commit log. It is accurate, complete, and useless — because it describes what happened to the code, and the reader needs to know what happened to them.

Core principle: The reader is deciding two things — should I upgrade, and what will break if I do. Every line either serves one of those decisions or is noise.

Companion skills: writing-internal-comms for audiences inside the org, coauthoring-docs for the documentation an entry links to, evolving-apis-and-schemas when the release contains a breaking change.

The Iron Law

EVERY ENTRY STATES WHAT CHANGED FOR THE READER, NOT WHAT CHANGED IN THE CODE

Refactored the auth middleware to use the new token store is a commit message. Sessions now survive a server restart is a release note. Same change, and only one of them answers a question the reader has.

If an entry has no reader-visible effect, it does not go in release notes at all. The commit log already exists and is one click away.