Guide
Most changelog entries are written for the wrong audience — the team that built the feature. They're full of internal terminology, vague verb clusters, and zero context for the person on the other end. The result is a changelog that exists but communicates nothing.
This guide will show you how to write entries that land.
The single most common mistake: leading with what changed technically rather than what it means for the person reading it.
Don't write
Refactored authentication middleware to support token refresh cycles
Write
You're no longer logged out unexpectedly during long sessions
Same change. Completely different experience for the reader. The first version is a commit message. The second is a changelog entry.
Before you write a single word, ask: what can the user do now that they couldn't before — or what frustration went away? Start there.
Bundling multiple changes under a single entry is tempting, especially when you're shipping a lot. Resist it.
Don't write
Improvements and fixes: faster load times, better error messages, updated settings page, misc bug fixes
Write
Settings page redesign — all your notification preferences are now in one place, with live preview as you change them
When you bundle, you bury. The reader has no way to know which of those five things matters to them. Separate entries are scannable. Bundles are noise.
The only exception: genuinely minor housekeeping (fixing a typo, correcting a broken link) can be grouped under a “Minor fixes” entry — but keep that list short and use it sparingly.
Use past tense, active voice, second person. It reads naturally and keeps entries short.
| Avoid | Use instead |
|---|---|
| “The export feature has been updated” | “Export now supports CSV and Excel” |
| “Users are now able to invite teammates” | “You can now invite teammates directly from the dashboard” |
| “Performance improvements were made” | “Search loads up to 3× faster” |
| “We have added dark mode” | “Dark mode is here” |
Active voice forces you to be specific. If you can't say who does what, you probably don't understand the change well enough to write about it yet.
Your changelog is not a pull request description. Nobody outside your team knows what “migrated to the new pipeline” means or cares about your internal architecture decisions.
Ask yourself: could a user who was never in a single planning meeting understand this entry? If not, rewrite it.
If a technical detail is genuinely important to your audience (security patches, API changes, breaking changes), explain the implication first, then add the technical context as a secondary detail.
Example
API change: The /users endpoint now requires an Authorization header. If you're using our SDK, nothing changes — this is handled automatically. If you're making raw requests, see the migration guide.
Here's a template that works for most entries:
[What changed, in plain language]
[Optional: why it matters or what problem it solves]
[Optional: any action the user needs to take, or a link to learn more]
In practice:
Example
Bulk actions in the task list
You can now select multiple tasks and archive, reassign, or delete them in one go. No more doing it one at a time.
Select tasks using the checkbox on the left, then use the action bar that appears at the bottom of the screen.
Short. Specific. Written for the reader.
Your changelog is a relationship touchpoint. It tells users you're actively improving the product and that you respect their time enough to explain what changed clearly.
Match your product's tone — if you're building a serious enterprise tool, stay professional. If you're building something lighter, a bit of personality in your entries is fine. What matters more than tone is consistency. Don't oscillate between formal and casual; pick a voice and stick with it.
Before you publish any entry, run through this:
Does it lead with the user benefit, not the technical change?
Is it one idea, not a bundle?
Is it past tense, active voice?
Could someone outside your team understand it?
Is the tone consistent with your other entries?
If all five are green, ship it.
Lokidrop makes it easy to publish beautiful changelogs your users will actually read.
Start for free