What is a changelog, and what goes in one?
5 min read
A changelog is the dated record of what changed in a product, written for the people the change affects rather than for the team that shipped it. Each entry names a change, says when it took effect, and says what the reader should do about it, which for most entries is nothing. That last part is what separates a changelog from a commit log: a commit log is a record for the people who wrote the code, and a changelog is a record for the people who use it.
What is a changelog, exactly?
It is a list of dated entries, newest first, each one describing a single change in terms the reader can act on. Not what the team built, but what is different now. “Refactored the billing service” is a commit message. “Invoices now show tax as a separate line item” is a changelog entry, because it tells the reader something they can check against their own account.
The format is old and deliberately plain: a heading per release or per day, a short list under it, sometimes a category label. Keep a Changelog is the most-cited spec for this shape, and it exists because most projects that skip a spec end up dumping their commit history instead, which answers a different question than the one a reader came with.
| Document | Written for | Answers |
|---|---|---|
| Changelog | Anyone using the product | What changed, and when? |
| Commit log | The team that wrote the code | What was done, in what order? |
| Release notes | Users deciding whether to update | What can I do now that I could not? |
| Patch notes | Players or users of a specific fix | What did this specific release fix? |
| Roadmap | Anyone wondering what’s next | What’s planned, and how far along is it? |
The five overlap in practice, but they are not the same document, and the difference is who is holding it when they read it. A changelog is the one built to be searched and linked back to later, which is why entries need dates and stable URLs more than the others do.
What does a changelog entry actually contain?
Four things, in order: what changed, stated in terms of what the user or caller would notice; when it took effect; what category it falls into (added, fixed, changed, removed are the common four); and, when it matters, what the reader has to do about it. A link to more detail is welcome. A paragraph of internal justification is not, because the reader did not ask why, they asked what.
## 2026-09-07
### Added
- Invoices now show tax as a separate line item, matching the customer's
account currency.
### Fixed
- Exporting a report as CSV no longer drops the last row when the report
spans more than 10,000 rows.That shape scales from a two-line update to a hundred-entry release without changing structure, which is the actual test of whether a format works: does it still read the same way on a busy week as it does on a quiet one.
Who writes a changelog, and when?
Whoever made the change, at the moment it ships, not a technical writer reconstructing it from tickets a week later. The person who touched the code knows what actually changed for the user; a summary written after the fact tends to describe the ticket instead, which is usually broader or narrower than what actually shipped. Some teams add a review step before an entry goes public, mainly to catch internal language that leaked through, and that review should happen fast enough that the entry still ships the same day.
Where does a changelog live?
On its own page, at a stable URL, syndicated as a feed. Buried in a settings menu or a release tag on a code host, it only reaches people who already knew to look. A public page means it can be linked from a support ticket, cited in a review, or subscribed to. The feed matters as much as the page: a reader who checks a product’s changelog once a month is rare, a reader who subscribes to it is not, and only the feed serves the second kind.
How does a changelog differ from release notes?
They are close enough to be confused constantly, and different enough that conflating them produces a document that serves neither reader well. Changelog vs release notes walks through the distinction in full; the short version is that a changelog is the complete, chronological record, and release notes are a curated subset written to make an update sound worth having. A product typically needs both, aimed at different moments in the reader’s day.
What makes a changelog worth reading?
Specificity and honesty about scope. “Various bug fixes” is the sentence that trains a reader to stop opening the page, because it promises nothing they can check. An entry that names the exact behavior that changed, even for a small fix, is the one that keeps a subscriber subscribed. The discipline extends to omission: a changelog that only ever announces wins, and never a fix for something that was broken, reads as marketing wearing a changelog’s clothes, and readers notice.
Versioning discipline matters too. Semantic versioning and your changelog covers how the version number and the entry should agree with each other, so a reader scanning the version history gets the same signal twice instead of two different ones.
How do changelogs get generated?
Two ways, and most real setups are a blend. Automated generation reads commit messages, usually Conventional Commits-formatted ones, and turns them into entries without a human touching the output; conventional commits to changelog covers that pipeline. Curated generation has a person write or edit every entry by hand. Automated output is faster and never misses a merged pull request, but it inherits every vague commit message verbatim, so most teams that automate still keep a light edit pass before publishing rather than shipping the raw output.
FAQ
Does every product need a changelog? Any product with users who are affected by change needs one, whether that is a SaaS app, an internal tool, or a public API. The shape adjusts (an API changelog reads differently from a consumer app’s), but the need does not.
What is a changelog in software terms? The same definition as above: a dated, chronological list of what changed in the software, written for the people who use it rather than the people who built it.
Can a changelog be auto-generated from commits? Yes, and many teams do exactly that, usually from Conventional Commits messages. The tradeoff is that a generated entry is only as clear as the commit message it came from, so a review pass before publishing catches the ones that need rewording.
Is a changelog the same as a version history? Close enough that the terms get used interchangeably. A version history is sometimes just a list of version numbers and dates with no description; a changelog always includes what changed.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.