CHANGELOG.md vs a public changelog page
One is for developers reading a diff, the other for customers deciding whether you are still shipping. Most products need both, and the second can be built from the first.
2 minute read
Two documents get called "the changelog", and confusing them is why so many public changelogs read like commit logs.
What each one is for
CHANGELOG.md |
Public changelog page | |
|---|---|---|
| Reader | Developers, often mid-upgrade | Customers and prospects |
| Ordered by | Version | Date |
| Language | The code's | The product's |
| Includes | Breaking changes, deprecations, APIs, internals | Anything a customer can see or do |
| Lives | In the repository | On your domain, and in your app |
| Read when | Something broke, or before upgrading | Someone wonders what is new |
A library, an SDK or a command-line tool needs the file. Anything with customers who never open your repository needs the page. Most products that sell software need both.
Keep a Changelog, briefly
The Keep a Changelog convention is the usual shape for the file: newest release first, a date written as YYYY-MM-DD, and entries grouped under Added, Changed, Deprecated, Removed, Fixed and Security.
## [2.4.0] - 2026-09-18
### Added
- Import from RSS, CSV and CHANGELOG.md
### Fixed
- Imported dates no longer shift by a day in negative timezones
It is a good format for its job, and a poor one for a customer page. "### Added" is a heading nobody outside engineering has ever wanted to read.
Writing both without writing twice
Write the file as part of the work, in the pull request. Then, when you publish:
- Drop what a customer cannot see. Dependency bumps, refactors, internal endpoints.
- Rewrite the titles as sentences. "Import from RSS, CSV and CHANGELOG.md" becomes "Bring your existing changelog with you".
- Merge the small things. Five fixes in one release are one entry called "Fixes this week", not five entries.
- Add the why. The file says what changed; the page says what it means.
That is about ten minutes per release, and it is the difference between a page people subscribe to and a page people close.
Keep the version number where it belongs
If customers install your software, put the version in the entry: they need to know what to upgrade to. If you run a web app, the version is an implementation detail, and the date plus a title is what matters.
Import the file you already have
If your public changelog is starting from years of CHANGELOG.md, you do not have to copy it across by hand. Relnotely reads a CHANGELOG.md directly: each release heading becomes an entry, the date in that heading becomes the entry's date, and the lines under it become the body. You see every entry before anything is saved, and you can rewrite the titles afterwards so they sound like a product rather than a diff.
That gets the page populated from day one, which matters more than it should: a changelog with three entries looks new, and a changelog with sixty looks like a company that ships.
Questions
- Is a CHANGELOG.md enough for customers?
- Rarely. It is ordered by version, written in the language of the code, and lives where customers do not go. It is the right file for developers upgrading a dependency and the wrong page for a customer wondering what is new.
- What is Keep a Changelog?
- A widely used convention for CHANGELOG.md files: entries grouped by release, newest first, with headings like Added, Changed, Fixed and Removed, and dates written as YYYY-MM-DD. It is a good format for a repository file.
- Do I have to write everything twice?
- No. Write the file as part of the work, then publish the customer-facing subset. Relnotely imports a CHANGELOG.md directly, so the release you already wrote becomes the page without re-typing it.
- Should my public changelog have version numbers?
- Only if your customers install versions. For a web app the date is the version, and a title describing the change is more useful than "v2.4.1".
Your changelog, on your own domain
One plan at $19 a month: your domain, the widget, subscriber emails, no watermark and no trackers on your readers. Writing is free — a card starts the 7-day trial when you publish.
Free tools
- Changelog Grader Score any public changelog out of 100, with the reasons.
- Release Notes Generator Turn commit messages into release notes, in your browser.
- CHANGELOG.md Validator Check a CHANGELOG.md against Keep a Changelog, line by line.