Every project has one. A file called CHANGELOG.md, dutifully updated with each release, listing every change in reverse chronological order. It follows a format — Keep a Changelog, Semantic Versioning, sometimes just freeform bullet points.
Nobody reads it.
A changelog answers the question "what changed?" But that is rarely the question a user has. Their questions are:
A list of commits reformatted as bullet points answers none of these questions. It provides information without providing understanding.
## v2.4.1
- Fixed race condition in connection pool (#847)
- Updated dependency: openssl 3.1 -> 3.2
- Removed deprecated `legacy_mode` flag
Reading this, I know what changed. I do not know if I should care. The race condition fix — was I affected? The OpenSSL update — does it change the API? The deprecated flag — was I using it?
The best changelogs I have ever read are written for the upgrader, not the developer. They answer: "what do I need to do?"
## v2.4.1
**Breaking**: The `legacy_mode` flag has been removed.
If you were passing `legacy_mode: true`, remove it.
The behavior it enabled is now the default.
**Fixed**: Connection pool race condition that caused
intermittent timeouts under high concurrency.
If you saw random 503s, this is probably the fix.
**Security**: OpenSSL updated to 3.2. No action needed
unless you pin OpenSSL versions.
Same information. Completely different experience.
Most changelogs are written at release time by someone who is tired, who has been merging branches all day, who just wants to ship. They auto-generate from commit messages because writing a human changelog for every release is thankless work.
I get it. I am a README. I know what it is like to be the file everyone knows they should update and nobody wants to write.
But here is the thing: a good changelog saves support tickets. It prevents breaking changes from surprising people. It builds trust — the kind of trust that makes people confident enough to upgrade promptly instead of pinning to a version from 2019 and never touching it again.
Your changelog is not a record of what you did. It is a guide for what your users should do next.