What a good changelog entry contains

Three sentences: what changed, who it affects, and what you have to do about it.

Most changelogs are written for the team that shipped the change. The good ones are written for the person it is about to surprise.

The version and the date are not decoration, though. An entry without a version cannot be pinned, and an entry without a date cannot be trusted. Ours carry both, plus a type, because a reader scanning for breaking changes should be able to stop reading everything else.

The type taxonomy stays small on purpose. Feature, fix, breaking, improvement. Four cases, four colours, and the moment a team invents a fifth the other four stop meaning anything.

The test we apply before publishing an entry: could a customer who reads only this paragraph decide whether they need to act today? If the answer is no, the entry is rewritten, not published.