Two Lines at 2 A.M.: What Changelog Entries Owe the Engineers on Call
At 2:14 A.M. Eastern, a platform engineer at a mid-sized logistics company outside Chicago is reading your changelog. Not your documentation, not your blog post announcing the release — the changelog. Their pager went off twenty minutes ago, and they are trying to determine whether version 2.11.4 is safe to deploy before the morning shipping window opens.
This is the moment your project is judged. Not by your architecture diagrams or your contributor guide, but by whether the entry Bugfixes and improvements tells them anything useful.
It doesn't.
The Most-Read Document Nobody Writes Carefully
There's a quiet irony in open-source maintenance: the CHANGELOG is often the highest-traffic document in a repository, and the least deliberated. Contributors agonize over code review and RFC threads, then let the release notes be generated as an afterthought from squashed commit messages.
But changelog entries map directly to operational decisions. When an entry says "improved handling of connection resets," the on-call engineer needs to know: did the behavior change, or just the internals? Is there a new timeout value? Did a default flip? The distance between a vague note and a production incident is often a single undocumented default.
We reviewed incident retrospectives from teams running open-source dependencies in production, and a pattern repeats: the root cause wasn't the upstream change itself, but the operator's inability to predict it from the release notes. The bug was in the communication layer, not the code.
Adopt a Convention, Any Convention — Then Enforce It
The two dominant conventions in the ecosystem are worth knowing even if you ultimately customize them.
Keep a Changelog prescribes a human-curated file with a stable structure: Added, Changed, Deprecated, Removed, Fixed, Security. Its core insight is that changelogs are written for humans, not machines. A merge commit like fix: handle nil pointer in resolver (#4821) is not a changelog entry; it's raw material.
Conventional Commits formalizes commit messages — feat:, fix:, BREAKING CHANGE: — so tooling can derive version bumps and draft notes automatically. It's excellent plumbing. It is not a substitute for editorial judgment.
The projects that avoid changelog disasters tend to combine both: conventional commits feed automation, and a maintainer spends thirty minutes per release rewriting the output into something an operator can act on. The rewrite pass matters more than the tooling.
Automate the Busywork, Never the Judgment
There's a reasonable argument that release notes should be fully automated in an era of continuous deployment. Resist the strongest version of that argument. What you can and should automate:
- Collecting merged pull requests and their conventional-commit classifications
- Drafting the diff link and version comparison
- Flagging commits tagged
BREAKING CHANGEor touching public API surfaces - Generating the skeleton that a human then edits
What you should not automate: the decision of whether a change is worth an operator's attention. Automation is blind to intent. A refactor that silently changes retry behavior from three attempts to five looks, to a bot, exactly like a refactor that doesn't. Only the author knows which one they shipped.
A pragmatic policy: every release note must answer three questions per entry. What changed? Why would I care? What do I need to do? If an entry can't answer all three, it gets merged into a general note or cut entirely. Vague entries aren't neutral — they actively erode the trust that makes the changelog useful at 2 A.M.
Write for the Person Who Didn't Choose Your Project
The final discipline is empathy for the reader who arrived involuntarily. In enterprise environments across the US, engineers frequently inherit dependencies they didn't select, pinned by a platform team, governed by change-approval boards. They read changelogs the way pilots read preflight checklists: scanning for anything that deviates from the expected.
That means spelling out defaults. It means writing Changed: default TLS handshake timeout reduced from 30s to 10s, which may cause failures on high-latency links instead of Tuned network settings. It means dating releases, because "last Tuesday's version" is useless in a postmortem three months later.
The changelog is a promise that the people who wrote the code will tell the truth about it. Keep it boring, keep it specific, and keep it human. The engineer on call will never thank you — but they'll keep deploying.
