Who writes the changelog, and who should
5 min read
Ask a team who writes the changelog and the honest answer is usually “whoever remembers to,” which is the same failure mode enforcing a changelog entry in CI exists to fix at the mechanical level. But forcing an entry to exist doesn’t decide who’s qualified to write a good one, and teams that skip that question tend to default to whoever’s easiest to require, usually the PR author, without checking whether that’s actually the person who can write it well.
Why doesn’t the PR author automatically make the best changelog writer?
Because they know the implementation, not necessarily the impact, and those are different kinds of
knowledge. Where do conventional commits stop covers this
gap from the commit-message side: fix(auth): reject expired refresh tokens is accurate and
useless to a customer, and the person who wrote that fix is often the person least equipped to
translate it, because they’ve been thinking in terms of the bug for hours and have lost the
outside view of what a user actually experienced. This is the same reason technical writers exist
as a profession: translating implementation into impact is a distinct skill from having built the
thing, and it takes practice regardless of how good the engineer is at the code itself.
Does that mean product or support should write every entry instead?
No, because they have the opposite gap: they know what matters to users but not always what actually shipped, which produces entries that are readable but occasionally wrong about scope, a “now supports X” claim for a feature that’s still behind a flag, or a fix described as complete when it only covers one of three cases. The failure mode of engineer-written entries is unreadable-but-accurate; the failure mode of PM-written entries is readable-but-unverified. Neither role owns both halves of what a good entry needs.
| Role | Usually gets right | Usually gets wrong |
|---|---|---|
| Engineer who wrote the code | Exact scope of what changed | Framing it for someone who didn’t build it |
| PM or support lead | Why it matters to the user | Precise boundaries of what actually shipped |
| Dedicated changelog owner | Consistent voice, cross-checks scope | Needs both of the above to check with |
What does a working ownership model actually look like?
A draft from whoever’s closest to the change, reviewed by whoever’s closest to the user, with one named person accountable for the final wording rather than everyone assuming someone else will catch problems. The draft needs to exist and be accurate more than it needs to be good; a rough engineer-written sentence that correctly says what changed is a better starting point than a polished but unverified one, because rewriting for clarity is easier than rewriting for correctness. The review step is where a PM or support lead reads the draft and asks the one question that catches the readability gap: would I understand this if I hadn’t seen the code.
Should the same person always be the accountable one, or does it rotate?
Named and stable beats rotating, at least for the final sign-off. A rotating owner means every entry gets reviewed by someone re-deriving the team’s conventions from scratch, which is exactly how voice drifts entry to entry and a reader starts noticing the changelog was written by committee. A single person, or a very small stable group, accumulates the judgment calls over time, when to say “improved” versus name the specific number, when a fix needs its own entry versus folding into a batch, and that judgment is worth more than distributing the labor evenly.
Draft (engineer, from the PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."
Reviewed (changelog owner, checked against the actual PR):
"Fixed: exports sorted by date could return results out
of order past the first page. Now consistent across all
pages."Does a small team need this much process for one line of text?
Not the roles as separate people, but the two steps still matter even solo. A one-person team is both the engineer and the reviewer, and the discipline that survives at that scale is doing the review as a separate mental pass, not skipping straight from writing the fix to publishing a description of it in the same breath. The trap at small scale is skipping the second pass entirely, not lacking a second person, because there’s no one external forcing it, and the accuracy gap that pass exists to catch doesn’t go away just because the same person could theoretically catch their own blind spot.
What happens when nobody is accountable for the final entry?
The changelog degrades unevenly instead of failing outright, which is worse because nobody notices until a reader points it out. Some entries stay sharp because whoever happened to write them cared; others go vague, “various improvements and bug fixes,” because whoever wrote them was moving fast and no one caught it before publish. Keep a Changelog’s format constraints catch structural drift, missing dates, wrong categories, but nothing in a template catches a vague entry that’s technically well-formatted, which is exactly the gap a named owner is there to close.
FAQ
Should the changelog owner be an engineering role or a product role? Either can work if the person has both technical fluency to verify scope and enough distance from implementation to write for an outside reader; the title matters less than whether they can do both halves, or know who to ask for the half they can’t.
Is a rotating on-call-style schedule ever appropriate for changelog ownership? For volume, sometimes, if the team is too small for one person to review everything; for voice and judgment, no, because that’s exactly what rotation erodes. A rotation that shares the drafting load while keeping one stable reviewer gets the benefit without the drift.
What’s the fastest sign something is wrong with the current ownership setup? Entries that are accurate but unreadable, or readable but wrong about scope, in a pattern that tracks who wrote them. If quality correlates with author rather than staying consistent, ownership is the gap, not writing skill.
Does automation reduce how much ownership matters? It reduces how much writing is needed, not how much judgment is needed. Changelog automation covers what a pipeline can safely generate, formatting, publishing, cross-posting; wording, grouping and what counts as worth mentioning stay human decisions no matter how much of the pipeline is automated.
What if the PR author and the reviewer disagree about the wording? The reviewer’s call, because the question they’re answering, would an outside reader understand this, is the one the role exists to protect. That doesn’t make the engineer’s read worthless: if the disagreement is about accuracy rather than phrasing, the reviewer defers, because scope is the author’s half to get right. Splitting the two kinds of disagreement, wording versus accuracy, stops most of these from turning into a standoff.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.