The changeloop blog
Release notes, in practice
Two things we think about a lot: how to write release notes anyone reads, and how to stop maintaining a changelog by hand. No newsletter, no gate. Just the writing.
Release notes practice
How teams write release notes people actually read.
-
Changelog vs release notes: what is the difference?
A changelog is a running record for people looking something up. Release notes are a curated message for people deciding whether to care. Here is the split.
-
How to write release notes people actually read
Bug fixes and performance improvements is not a release note. Here is the question every entry has to answer, and a before and after rewrite of a real one.
-
Release notes best practices worth keeping
Most best practice lists for release notes are style advice. These are the ones that change what a reader does, and three popular ones that are cargo cult.
Engineering
Changelogs as a build artifact: conventions, automation, pipelines.
-
Changelog automation, and its limits
Automate collection, formatting and publishing. Do not automate selection or wording. Here is where the line sits and what happens each time it moves.
-
Keep a Changelog, actually implemented
The spec is one page and takes ten minutes to read. Implementing it is where teams drift. Here is what it says, what it leaves open, and where it goes wrong.
-
From conventional commits to a changelog
Conventional commits make a changelog derivable. They do not make it readable. Here is what the convention buys, where it stops, and how to bridge the gap.
