Guide
You've shipped something. Now comes the question every team quietly argues about: does this need a changelog entry?
Ship too much and your changelog becomes noise — readers stop trusting it. Ship too little and users miss things that matter, or feel blindsided by changes they weren't told about. Getting the threshold right is one of the most important habits a team can build.
One question covers most cases:
Would a user notice this change without being told?
If yes, it deserves an entry. If no, it probably doesn't.
“Notice” doesn't mean they'd be delighted or frustrated — it means the product feels different in any way. A new button they'll see. A flow that now works differently. A limit that changed. A thing that used to break that now doesn't.
If the change is invisible to everyone outside your codebase, it's almost certainly not a changelog entry.
New features
Anything a user can do now that they couldn't before. Even small ones — a keyboard shortcut, a filter option, a new export format. These are the entries users look forward to.
Behaviour changes
If something worked one way and now works differently, users need to know. Even if the new behaviour is better, the surprise of an unexplained change erodes trust faster than the improvement builds it.
Removals
Anything that goes away — a setting, an endpoint, a plan feature — must be documented. Users who relied on it deserve notice, and users who discover the removal without context assume it's a bug.
Fixes for known, visible bugs
If users reported it, asked about it, or worked around it — tell them it's fixed. This closes the loop and shows the team is listening.
Performance changes users can feel
If a page that took four seconds now takes one, that's worth a line. Keep it brief and specific: “Dashboard now loads up to 3× faster for accounts with large datasets.”
Security patches
Always document these, even vaguely. Users and compliance teams need to know. You don't have to reveal the vulnerability — just that a security issue was resolved and when.
Pricing or limit changes
No exceptions. If a free tier limit drops, a paid feature moves tiers, or pricing changes in any way, publish an entry before the change goes live.
Internal refactors
Rewriting a service, splitting a module, migrating to a new framework — if nothing changed for the user, nothing needs to be said. These are commit messages, not changelog entries.
Dependency upgrades
Bumping a library version, updating a runtime, patching a transitive dependency — skip it unless it directly affects behaviour the user can see or it resolves a security issue.
Fixes for bugs users never encountered
If a bug existed only in edge cases nobody hit, or was caught and fixed before it ever reached production, there's nothing to communicate.
Development tooling
CI pipeline changes, deployment process improvements, test coverage increases — invisible to users, irrelevant in a changelog.
Copy tweaks and minor visual polish
Fixing a typo in a label, adjusting spacing, tweaking a colour to meet contrast ratios — these don't meet the “would they notice” bar. Bundle the rare exceptions into a periodic “polish” entry if needed.
Some changes are genuinely hard to call. Here's how to handle the common ones.
Performance improvements users might not notice
Small speed gains aren't worth a dedicated entry. Meaningful ones are. Use your judgement: would a user who's complained about slowness care? If yes, ship an entry.
Behind-the-scenes infrastructure changes with reliability impact
If you moved to a new database cluster or switched CDN provider and it means better uptime or lower latency, you can mention it briefly — but only if it produces a user-observable result. “We upgraded our infrastructure” is not an entry. “We've improved uptime reliability for users in Southeast Asia” is.
Bug fixes for issues users worked around but didn't report
If the workaround was common enough that you've seen it in support tickets or user feedback, publish the fix. If it's theoretical, skip it.
Experimental or beta features
Document these, but label them clearly. Users who opt in to beta features deserve a changelog too — just make the beta status visible in the entry.
When in doubt, run the change through this:
Did something change that a user can see, feel, or rely on?
→ Skip it. Write a commit message instead.
→ Does it add, remove, or meaningfully change behaviour?
→ Ship an entry
→ Ship an entry (before it happens)
→ Ship an entry
→ Ship an entry
→ Skip it, or batch into a polish note
When genuinely unsure, publish. A slightly generous changelog builds more trust than a sparse one. Users who read an entry about a change they didn't notice lose nothing. Users who discover an undocumented change that affected them lose trust — and sometimes more.
The cost of one unnecessary entry is low. The cost of a user feeling blindsided is high.
Before deciding to skip an entry, ask:
Would a user notice this change without being told?
Did it add, remove, or change any behaviour?
Is it a fix for a bug users experienced or reported?
Does it affect pricing, limits, or access?
Is it a security patch?
If any answer is yes, write the entry.
Lokidrop makes it easy to publish beautiful changelogs your users will actually read.
Start for free