The changelog nobody reads

Most changelogs are written for the person who wrote the change, not for the person who has to read it later. That is why they bloat, and why nobody reads them.

Why entries grow

The author just finished the work and remembers every step: the false start, the file that surprised them, the edge case they chased for an hour. All of that is fresh, so it goes into the entry. The result reads like a diary, not a release note.

What a reader actually scans for

Someone scanning a changelog wants two things: what changed, and where they will notice it. They are deciding whether to upgrade, or trying to explain a new behavior they just saw. They are not trying to relive how the change was made.

The one-paragraph rule

Write one paragraph per release: name what changed and where a reader notices it. Nothing else. The deep why and how belongs in the pull request, where it stays linked to the diff and searchable. A changelog is a summary, not an archive.

When a long entry is justified

Breaking changes are the exception. If an upgrade requires the reader to change their own code, spell out exactly what breaks and what to do about it. That is information they cannot get anywhere else in time to act on it.