---
title: CHANGELOG.md vs a public changelog: which do you need?
description: The difference between a Keep a Changelog file in your repository and a customer-facing changelog page — who reads each, what goes in them, and how to keep both without writing twice.
canonical: https://relnotely.com/blog/changelog-md-vs-public-changelog
published: 2026-09-20
updated: 2026-09-20
---

# 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.

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](https://keepachangelog.com) 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.

```markdown
## [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:

1. **Drop what a customer cannot see.** Dependency bumps, refactors, internal endpoints.
2. **Rewrite the titles as sentences.** "Import from RSS, CSV and CHANGELOG.md" becomes "Bring your existing changelog with you".
3. **Merge the small things.** Five fixes in one release are one entry called "Fixes this week", not five entries.
4. **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".

---

Published by Relnotely at https://relnotely.com/blog/changelog-md-vs-public-changelog