changelog
The changelog
Who it is for
CHANGELOG.md is read by someone whose integration just broke, at the moment it broke. They are not reading it to admire the work; they are looking
for the line that explains what happened to them.
For a service, that reader is whoever calls your API — another team, a mobile client, a partner — plus whoever is on call at 3am wondering what shipped. For a published library it is whoever bumped your version. Same file, same discipline, different blast radius.
That single fact settles most questions about it. Write the entry from the caller's side, not from the diff's side. "Refactored the search
adapter" is written from inside. "GET /books?sortBy= silently ignored an unknown field instead of rejecting it, so a typo returned unsorted results
that looked plausible" is written from outside — and it is the one that saves someone an afternoon.
The commit message and the changelog entry answer different questions and are not interchangeable. The commit explains the change to whoever maintains
the code; the changelog explains the consequence to whoever depends on it. Load the ktor-toolkit:commit skill for the other half.