A changelog is a dated, ongoing record of what shipped, version by version, in the order it happened. It is not the same thing as release notes, which announce one release at a time, and it is not a roadmap, which describes what has not shipped yet. This guide covers what each one is, where a changelog should live, how to date and group entries, and how to run one without it becoming a chore.
What is a changelog?
A changelog is the record itself: version numbers, dates, and a short line per change, going back as far as the project does. Its job is to answer one question for a returning visitor: what changed since I last looked? A good changelog answers that in seconds, without making the reader open every release to find out.
Most small products do not need a separate changelog and set of release notes. One dated, grouped list, published as the release happens, covers both jobs. The distinction matters more once several contributors ship in parallel, or once the changelog doubles as an announcement people actually read.
How is a changelog different from release notes?
A changelog is the whole history in one place. Release notes are the write-up for a single release, often with more explanation, sometimes a screenshot, sometimes a sentence of context about why a change happened. Think of the changelog as the ledger and release notes as the announcement drawn from one line of it.
In practice the two blur together for most teams, and that is fine. What matters is the writing, not the label: state the effect for the reader, not the mechanism in the code. How to write release notes covers who release notes are actually for, why "various bug fixes and improvements" fails every reader who sees it, and how to translate an internal fix into a sentence a user would recognise. Release notes examples shows the five patterns, illustrated with before-and-after lines, that separate a release note people skim from one they ignore.
How is a changelog different from a roadmap?
A roadmap looks forward. It lists what you intend to build, and nothing on it is certain until it ships. A changelog looks backward. Everything on it happened, on a specific date, and it is not going to move.
| Changelog | Release notes | Roadmap | |
|---|---|---|---|
| Direction | Backward, the whole history | Backward, one release | Forward, not yet shipped |
| Certainty | Definite, it shipped | Definite, it shipped | A plan, can change or slip |
| Format | Dated list, grouped by version | Short write-up per release | List or board, often voteable |
| Answers | What changed since I last looked? | What's new in this release? | What might come next? |
| Typical reader | A returning user, checking | Everyone, right after a release | A user deciding whether to wait |
Keeping the three separate matters for one practical reason: a roadmap item that has not shipped does not belong in a changelog, however close it is. Mixing the two trains readers to distrust the changelog, because now some of its entries are promises rather than facts.
Who reads each one?
Three kinds of reader show up for a changelog or release note, and none of them is asking how the code works. An existing user skims it to check whether anything they rely on moved. A frustrated user checks whether the exact thing they reported got addressed. Someone evaluating the product for the first time reads it as a proxy for whether the product is actively maintained, which makes an empty or stale changelog a quiet reason not to buy.
A roadmap has a narrower audience: people deciding whether to wait for something rather than switch tools now. That is a real, useful job, but it is a different job from either of the other two.
Where should a changelog live?
On your own domain, not inside a vendor's dashboard. A changelog that only existed behind a login, or on a subdomain you do not control, cannot be indexed the way a page on your own site can, cannot be linked to from your own product, and disappears the day you stop paying that vendor. Frill.co's own product page states this limit plainly: "No SDK to install. No OAuth flow. No self-hosting." Its changelog tool, like most in the category, is a feature of the platform, not a page you own.
Fider is the clearest case of a tool where the changelog is simply absent. It ships a roadmap, voting and private boards, but no changelog at all, and its own maintainer, Northern App Labs Ltd, tells new users on their documentation that "the easiest way to get started with Fider is to use our Cloud Instance" rather than run it yourself. If you want the board, the roadmap and the changelog together, on your own domain, you need a tool that treats all three as one product rather than an add-on.
That is the reasoning behind how Docket ships: the free edition includes bugs and feature requests, roadmap, changelog, FAQ and a custom domain together, with no separate purchase for any of them. Because the whole site is static files plus two small endpoints rather than a database-backed application, the changelog is just pages in your own repository, which is also your backup.
How do you version and date entries?
Every entry needs a date. That single habit is what makes "what changed since I last looked" answerable at a glance, and a changelog with undated entries is not really a changelog, just a list.
Most teams pair dates with a version number, and semantic versioning, three numbers separated by dots, is the common choice: a patch-only release bumps the last number, a release that adds something bumps the middle one, and a release that breaks something bumps the first. The Keep a Changelog format is the named convention for going further: six specific categories for what kind of change happened, and the rule that a change with no user-facing description does not belong in the file at all. Changelog examples shows what an entry looks like once you separate the commit message from the sentence a reader actually needs, with a working comparison table of weak versus strong wording.
One payment, no subscription, unlimited products.
What is the Unreleased section for?
It solves a specific, ordinary failure: a change ships, writing it up gets pushed to "before the next release," and then the release happens and nobody remembers because the moment has passed. An Unreleased section at the top of the changelog gives every merged change a home the day it lands, before there is a version number or a date to attach to it. When the release actually happens, that section gets renamed to the new version and date, and a fresh, empty Unreleased section opens above it. The full mechanics, including why newest-first order is the only order anyone actually reads a changelog in, are in the Keep a Changelog format.
How does a changelog close the feedback loop?
The most underused move in this whole category is linking a changelog entry straight back to the request that asked for it. Someone filed a bug or asked for a feature, watched it sit on a board for weeks, and then it ships silently in a changelog entry they never see, because nothing connects the two. That gap is why people stop bothering to file requests at all.
UserJot's own product does this automatically: when a request is marked complete, its AI drafts the changelog entry from the original request and then emails every voter and commenter who asked for it. You do not need automation to get the same effect. If your feature request board and your changelog are the same product, on the same domain, a single link from the shipped entry back to the original request costs nothing and closes the loop for everyone who voted on it.
What do you do when nothing user-facing shipped?
Leave it out. A release with a backend migration, a dependency bump, or a refactor that changed nothing a user can see, click or notice is real work, but it is not a changelog entry. Writing one anyway, in the shape of "various improvements," answers a question nobody asked and tells the reader that nothing else in the note was worth writing either. The test that settles it: if you deleted the entry, would a single user notice something now behaves differently? If not, it does not belong in the file. How to write release notes goes through this in more depth, including how to translate a genuinely user-facing fix into a sentence a reader recognises rather than a description of the code.
How often should you publish?
As often as something ships that a user would notice, and no more often than that for the sake of it. A changelog padded with entries nobody would notice trains readers to stop reading it, the same failure as writing "bug fixes and improvements" in the first place.
Freshness genuinely matters beyond your own readers, too. Pages that AI systems cite are disproportionately recent: in one study of 7,683 pages and 47,097 citations, 75 per cent of cited pages had been updated within the past year, and update date mattered more than original publish date, 72 per cent against 42. A changelog that has not moved in months reads as an abandoned product to a human evaluating it and to whatever is summarising your site for someone else. The honest way to earn that freshness is to publish when something real ships, not to fake it: one competitor in this category, Canny.io, revises the modified date on old posts rather than publishing new ones, and sorts its own blog index by modified date rather than published date. A changelog does not have that shortcut available. Either something shipped on that date, or it did not.
Where to go next
This page is the overview. Each part of it has a page of its own.
- The format and the craft. Keep a Changelog, the format explained, how to write release notes, and how to write patch notes, which is a different genre with a more invested audience.
- Things to copy. Changelog examples worth copying, release notes examples people actually read, and release notes templates you can copy.
- The page itself. Changelog page design works through twelve layouts and how each one fails.
- Numbering. Semantic versioning, and what to put in the changelog, including when the scheme does not suit how you ship.
- Getting it written. Writing changelogs from commits, and why a commit log is not a changelog.
- Tools. Best changelog tools in 2026 sorts by where the changelog lives, and best release notes tools in 2026 sorts by how the notes actually reach a reader.
Frequently asked questions
Is a changelog the same thing as release notes?
Not quite. A changelog is the whole ongoing history, one dated entry per change. Release notes are the write-up for a single release, sometimes with more explanation or a screenshot. For most small products the two collapse into one dated, grouped list, and the label matters less than writing the effect for the reader rather than the mechanism.
Do I need a roadmap as well as a changelog?
Only if you want to tell people what might come next. A roadmap is forward-looking and uncertain; a changelog is backward-looking and definite. Keep the two separate: an unshipped roadmap item does not belong in the changelog, because mixing plans with facts trains readers to distrust the whole file.
What date format should a changelog use?
Any format a human reads unambiguously, applied the same way every time. The important habit is not the format, it is that every single entry has one. A changelog without dates cannot answer "what changed since I last looked," which is the one question it exists to answer.
Should every commit get its own changelog entry?
No. Only changes a user would notice belong in the file. A backend migration, a dependency bump or a refactor with no visible effect is real work, but writing it up as a changelog entry answers a question nobody asked and buries the entries that do matter.
Where should the changelog live on my site?
On your own domain, ideally next to the feature request board it should link back to. A changelog trapped inside a vendor's dashboard cannot be indexed the way a page on your own site can, and it disappears if you ever stop paying for that vendor. Several tools in this category, including Frill.co, do not offer self-hosting at all.