A changelog people read groups entries by what changed for them, states the user-visible effect rather than the commit message, and dates every version. A changelog nobody opens is a list of commit messages with build numbers as headings. The difference is not effort, it is who the writer imagined reading it.
This page is one part of a larger guide. For the whole subject in one place, see changelogs and release notes.
How should you group entries?
Pick a small, consistent set of categories and use them every time, so a returning reader can scan a release in seconds without reading every line. Most teams manage fine with three or four:
| Category | What lands here | Example entry (illustrative) |
|---|---|---|
| New | A capability that did not exist before | "Added CSV export for the roadmap board." |
| Improved | Something that worked, now works better | "Search now matches partial words, not just whole ones." |
| Fixed | Behaviour that was wrong, now is not | "Exporting a board with zero votes no longer fails." |
| Removed | Something taken away or replaced | "Removed the legacy weekly digest email." |
Those four categories are invented for this example, not a standard. If you want a named, stricter convention instead of picking your own, the Keep a Changelog format defines six categories and the rules for using them.
Whichever set you pick, the failure mode is the same: entries with no category at all, dumped under a version number in whatever order they shipped. A reader cannot scan that. They have to read the whole thing to find out if anything matters to them, and most will not bother.
Should the entry describe the commit or the effect?
The commit message describes what changed in the code. The changelog entry describes what changed for the person using the product. They are rarely the same sentence.
| Commit message | Changelog entry (illustrative) |
|---|---|
fix: null check in export handler | "Exporting a board with zero votes no longer fails." |
feat: add csv writer for roadmap export | "Added CSV export for the roadmap board." |
perf: debounce search input by 200ms | "Search results now appear as you type, without the earlier lag." |
The commit message is written for the person who wrote the code, an hour after writing it. The changelog entry is written for someone who has never seen the code and does not want to. If an entry only makes sense to someone who already knows how the feature is built, it needs rewriting, not shipping.
Example release note (illustrative)
2.4.0, 14 August 2026
- New: Added CSV export for the roadmap board.
- Improved: Search now matches partial words, not just whole ones.
- Fixed: Exporting a board with zero votes no longer fails.
Every line above is invented for this article, not a real release. It is here to show the shape: a version heading with a date, entries grouped by category, and each one a sentence about the effect rather than the mechanism.
What goes in a version heading?
Two things, always: a version identifier and a date. The version identifier can be a number, a build, or a date itself, but it has to be stable enough that someone can say "we shipped that in 2.4.0" and be understood a year later. The date matters just as much: a changelog with no dates cannot answer "was this recent," which is often the only question a reader actually has.
Put the newest version at the top. Nobody opens a changelog to read history from the beginning; they open it to see what changed since they last looked, which is always the most recent entry.
How do you link a shipped item back to the request that asked for it?
This is the pattern that turns a changelog from a broadcast into proof that voting works. When a shipped item started life as a feature request someone filed and other people voted on, link the changelog entry back to that request. The person who asked sees their request marked shipped in the same place they filed it, and everyone who voted gets to see the thing they wanted actually arrived.
UserJot builds this directly into its workflow: when a request is marked complete, it drafts the changelog entry from the original request text and emails everyone who voted or commented on it. That is the pattern working end to end, not just a link but a notification, and it is worth copying the shape of even without the automation.
One payment, no subscription, unlimited products.
What about internal changes nobody asked for?
Not everything you ship belongs in a customer-facing changelog. A dependency bump, an internal refactor, a test suite change: none of that changed anything the person using the product can see, and listing it dilutes the entries that do matter. If nobody outside the team could tell the difference before and after, leave it out.
Security fixes are the exception worth handling carefully rather than skipping. They belong in the changelog, because "we fixed a security issue" is information a customer might reasonably want, but the entry should describe that a fix shipped without describing the vulnerability itself while it is still being patched elsewhere. This is common enough that it gets its own named category in the Keep a Changelog convention.
The test that works for most changes: would a customer notice, or would they only understand the entry by reading the code? If it is the second one, it is not a changelog entry, it is a commit message that wandered into the wrong file.
Frequently asked questions
Does a changelog need to list every single change?
No. It needs to list every change a customer would notice or care about. Internal refactors, dependency bumps, and test changes with no visible effect can be left out entirely. A changelog that lists everything reads like a commit log with extra formatting, and the entries that matter get buried in the ones that do not.
What if a release only fixes internal things?
Then it may not need a public changelog entry at all. Not every version bump has to produce a customer-facing line. Some teams still note "maintenance and reliability work" as a single line so the changelog stays continuous, but inventing user-facing language for a change nobody can see is worse than skipping it.
Should a changelog entry mention the person who reported the bug?
That is a product decision, not a formatting rule. Linking the entry back to the original request already gives credit implicitly, since the requester can see their own name on the thread it points to. Naming them directly in the entry itself is optional and depends on whether your board is public.
How long should a single entry be?
One sentence, stating the effect. If an entry needs two sentences to explain what changed, it is usually because it is describing the mechanism as well as the effect, and the mechanism can come out. A reader scanning ten entries in ten seconds is the target, not a reader studying one entry for a minute.
Is a changelog the same thing as release notes?
In practice, most products use the words interchangeably. Where teams draw a line, "changelog" tends to mean the running, entry-by-entry list, and "release notes" tends to mean a longer, more narrative write-up for a single version, sometimes with screenshots or context the changelog entry does not have room for.