"Changelog" gets used loosely, sometimes for a developer's CHANGELOG.md, sometimes for a customer-facing "What's new" page. They share a spine: a dated list of notable changes, newest first.
The distinction that matters is who it is for. A changelog written for the people who use the product looks different from one written for the people who build it, and confusing the two is why so many public changelogs read like commit history.
Direct answer
A changelog is a chronological, dated record of the notable changes to a product, one entry per release, written for the people who use it. It differs from release notes mainly in scope: a changelog is the ongoing archive of every notable change, while release notes are the narrative announcement for a single release. Many teams publish both, and DocsKoala keeps a public changelog current by drafting entries from merged pull requests.
What belongs in a changelog
- New features and capabilities the reader can now use.
- Meaningful improvements to existing behavior.
- Bug fixes for issues a customer could have noticed.
- Deprecations and breaking changes, flagged clearly and early.
Each entry is dated, written impact-first, and ideally links to the help article that explains the change in full. What does not belong: internal refactors, dependency bumps, and anything a customer could not observe.
Changelog vs release notes
| Changelog | Release notes | |
|---|---|---|
| Scope | Every notable change over time | One release |
| Shape | A running, dated list | A narrative write-up |
| Primary use | Look up when something changed | Announce what just shipped |
| Lifespan | Permanent archive | Point-in-time |
In practice they are two views of the same underlying facts. The healthiest setup generates the changelog entry and the release-note announcement from the same source of truth so they never disagree.
Why changelogs go stale, and how to stop it
A changelog is only useful if it is complete. The moment a few releases ship without an entry, readers stop trusting it as the record, and an untrusted changelog is worse than none because it implies coverage it does not have.
Frequently asked questions
Is a changelog the same as release notes?
No. A changelog is the ongoing, dated archive of every notable change. Release notes are the narrative write-up for a single release. They overlap heavily and are often generated from the same source, but a changelog is the permanent record and release notes are the announcement.
Should a changelog be public?
A customer-facing changelog usually should be. It builds trust, gives support and sales a reference, and signals an actively maintained product. Internal-only changelogs (like a CHANGELOG.md in a repo) serve a different, developer audience and can stay private.
How often should you update a changelog?
Every time a customer-visible change ships. The value of a changelog comes from being complete, so the update cadence should match your release cadence rather than a fixed schedule. Automating the entry from the merge is the only way this stays reliable at speed.
Conclusion
- A changelog is the dated, running record of notable product changes, written for users.
- Release notes are the announcement for one release; a changelog is the archive of all of them.
- Its value comes from being complete, which is exactly what manual upkeep erodes.
- Tie entries to merged changes so the record never falls behind, which DocsKoala does automatically.