Release notes and changelog

Release notes are read by someone deciding whether to care. They are scanning for the thing that affects them, and the two most common formats both defeat that: a wall of commit messages, or a marketing summary that omits everything specific.

The useful shape is between them. Grouped by impact, specific enough to act on, and complete.

The operational shape

Trigger. A release.

Reads. Release data from product. Voice, lightly.

Cadence. Per release, without exception — this is a record, and the completeness is the point.

Gate. Notify after, accuracy-checked.

What good looks like

Grouped by who is affected, not by what changed. New capabilities, behavior changes, fixes, deprecations. Component-based grouping reflects how the software is organized, which the reader does not know and should not need to.

Behavior changes are called out separately and first. Anything that alters something people already do is the highest-value entry on the page, and burying it among new features is how a customer finds out by being confused.

Fixes are included and described honestly. A changelog containing only improvements reads as marketing. The fixes are also what people search when something started working differently — and finding the entry converts confusion into confidence.

Every entry is dated and versioned. The record's value is entirely in being able to answer "when did this change," and that question gets asked during incidents.

It links to depth rather than containing it. An entry names the change and points at the documentation. Explaining fully in the changelog puts the explanation somewhere nobody will look for it later.

When it goes stale

Release notes do not go stale. They are a dated record, and being old is what makes them useful. A note from two years ago is not wrong; it is history, and history is the whole product.

The failure here is absence. Three forms. A release shipped without a note, which puts a hole in the record exactly where somebody will later need it. Entries written in terms nobody outside the team understands, which is presence without usefulness. And the changelog stopped being maintained, usually gradually, until nobody trusts it enough to check.

This makes it the only capability in the set whose review question is not "is this still true" but "is this complete."

What it feeds

• Product update emails — the filtered, segmented version for people who will not read a changelog
• Support and the knowledge base — the answer to "when did this change" during an incident
• Retention and trust — a maintained changelog is one of the cheapest credible signals that a product is actively worked on