Changelogs are a strange kind of document. Almost everyone who uses a project reads them at some point, usually right before an upgrade, and usually in a hurry. Yet they're often written last, quickly, and by copying commit messages into a list.
When I edit a changelog, I try to read it as the person who has to decide whether to upgrade today. Here's what I look for.
Commit messages are not changelog entries
A commit message is written for the people working on the code. A changelog entry is written for the people using it. The two overlap, but not much.
To see what changed since the last release, I start with the commit list:
git log --oneline v1.4.0..HEAD
This shows every commit after the v1.4.0 tag, one per line. It's raw material, not the changelog. Lines like fix typo, refactor parser, or bump deps may matter to contributors, but most users don't need them. What I want are the changes a user would notice: something new, something that behaves differently, something that stopped working, or something that got fixed.
Group by what the reader needs to do
A flat list of twenty items makes the reader do the sorting. I prefer the grouping from the Keep a Changelog convention: Added, Changed, Deprecated, Removed, Fixed, and Security. Even if a project doesn't follow that convention fully, the headings answer the questions people actually have.
## [1.5.0] - 2026-10-29
### Added
- Export to CSV from the Reports page.
### Changed
- Dates in exported files now use the YYYY-MM-DD format.
### Fixed
- Search no longer ignores words with accents.
Anything under Changed or Removed deserves a second look, because that's where upgrades break.
Lead with the effect, not the code
Here's a typical entry before editing:
- Refactored date handling in exporter module
And after:
- Dates in exported files now use the YYYY-MM-DD format.
If you parse exports with a script, update the date format there.
The first version describes work that was done. The second describes what the reader will see, and what they might need to do about it. I ask myself one question for each entry: if this were the only line someone read, would they know whether it affects them?
Make breaking changes impossible to miss
A breaking change hidden in the middle of a list is the most expensive mistake a changelog can make. I move these to the top of the release section and mark them clearly, so nobody has to search for them:
### Removed
- **Breaking:** the `--legacy-output` option is gone.
Use `--format=v1` for the old output.
The replacement goes right next to the removal. "Removed X" on its own leaves the reader with a problem; "Removed X, use Y instead" gives them a way forward.
Use the same words as the interface
If a button says "Export", the changelog says "Export", not "download", "save as file" or "data dump". Readers search changelogs for the words they see on screen or type in the terminal. Keeping the names identical makes those searches work, and it matches the rest of the docs.
Date and order consistently
Two small rules save a lot of confusion. First, newest release at the top. Second, one date format everywhere. I use YYYY-MM-DD because it doesn't mean different things in different countries, and it sorts correctly as plain text.
A quick read before it ships
My last check is simple. I read only the section headings and the first few words of each entry. If that skim tells me what changed and whether I need to act, the changelog does its job. If I have to read every line to find the one breaking change, it goes back for another edit.
Top comments (0)