Writing Changelog Entries in English: Clear, Scannable Release Notes
Write changelog entries that users actually read — clear verbs, consistent categories, user-facing language and breaking-change notices — with templates and before/after examples.
A changelog is read by people deciding whether to upgrade, debugging a regression, or just keeping up with your project. They skim. If your entries are vague (“various fixes”), internal (“refactored the FooService”), or inconsistent, the changelog stops being useful. This guide shows you how to write clear, scannable changelog entries in English.
What a changelog is for
A changelog answers one question for the reader: “What changed that affects me?” That word — me — is key. The reader is a user of your software, not a contributor. Write for them, not for your git log.
Internal (bad): “Refactored AuthManager to use the new TokenStore.” User-facing (good): “Fixed login occasionally failing after a token refresh.”
The first describes how you changed the code; the second describes what the user experiences. Changelogs are about effects, not implementation.
Use the standard categories
The widely adopted Keep a Changelog format uses these headings. Sticking to them makes your changelog instantly familiar:
- Added — new features.
- Changed — changes to existing behaviour.
- Deprecated — features that still work but will be removed.
- Removed — features taken away.
- Fixed — bug fixes.
- Security — vulnerability fixes.
Group entries under these headings within each version. Readers learn to jump straight to Fixed or Breaking.
## [2.4.0] - 2026-06-13
### Added
- Dark mode for the dashboard.
### Fixed
- Login failing when the email contained a `+`.
### Security
- Patched an XSS in the comment field (CVE-2026-1234).Start each entry with a verb
Changelog entries are scannable when they begin with a consistent verb form. Use either the past tense (“Added”, “Fixed”) or the imperative (“Add”, “Fix”) — but pick one and never mix.
- “Added keyboard shortcuts for navigation.”
- “Fixed crash when uploading files over 2 GB.”
- “Improved search performance by 40%.”
- “Removed the deprecated v1 API.”
Strong, specific verbs:
- Added, Introduced — new things
- Fixed, Resolved — bugs
- Improved, Optimised, Sped up — performance/UX
- Changed, Updated, Renamed — modifications
- Removed, Dropped, Deprecated — taking away
Avoid empty verbs: “Updated some things,” “Various improvements,” “Misc fixes.” They tell the reader nothing.
Be specific and quantify
Vague entries waste the reader’s time. Add the detail that lets them judge relevance.
Vague: “Improved performance.” Specific: “Reduced dashboard load time from 3s to under 1s.”
Vague: “Fixed a bug.” Specific: “Fixed timestamps showing in UTC instead of the user’s local time.”
Quantify whenever you can: “40% faster,” “files up to 5 GB,” “reduced memory by half.” Numbers make a changelog credible and useful.
Highlight breaking changes loudly
Breaking changes are the entries readers must not miss. Flag them clearly — many projects use a dedicated section or a bold marker.
- “BREAKING: The
/v1/usersendpoint has been removed. Use/v2/users.” - “Breaking change: The config now requires a
regionfield.” - “⚠️ The default timeout changed from 30s to 10s.”
Always tell the reader what to do about it, not just what changed:
“BREAKING:
parse()now throws on invalid input instead of returningnull. Wrap calls in a try/catch or validate input first.”
A breaking change without migration guidance just creates support tickets.
Write in plain, user-facing language
Drop internal names and jargon the reader doesn’t share:
Internal: “Bumped the GraphQL resolver batch size in the DataLoader.” User-facing: “Reduced loading times on pages with many items.”
Reference features and behaviours users see, not classes and modules they don’t.
Also avoid:
- Ticket numbers as the whole entry: “Fixed PROJ-1234.” (Link it, but describe it too.)
- Apologies and chatter: “Sorry for the bug everyone, we finally fixed it!” Keep it factual.
Keep tense and voice consistent
Pick a style for the whole changelog and hold it:
- Tense: past (“Added”) or imperative (“Add”) — not both.
- Voice: prefer active and concise. “Fixed the crash,” not “The crash was fixed.”
- Capitalisation: consistent — sentence case is most common.
- Punctuation: decide whether entries end in a full stop and stick to it.
Inconsistency makes a changelog look careless and is harder to scan.
Before and after
Before
## v2.4.0 - fixed some stuff - refactored AuthManager - PROJ-1234 - made it faster - removed old api (might break things)
No categories, internal names, vague verbs, and a breaking change buried as a casual aside.
After
## [2.4.0] - 2026-06-13 ### Added - Dark mode for the dashboard. ### Changed - Reduced dashboard load time from 3s to under 1s. ### Fixed - Login failing when the email contained a `+` (PROJ-1234). ### Removed - **BREAKING:** The v1 API has been removed. Migrate to v2 — see the upgrade guide.
Same release, but now a reader can scan it in five seconds and knows exactly what affects them.
Common mistakes
- Writing from the git log. Translate implementation changes into user-visible effects.
- Vague entries. “Various fixes” and “improved performance” help no one — be specific.
- Burying breaking changes. Flag them loudly and give migration steps.
- Inconsistent verb tense. Choose past or imperative and never mix.
- Internal names. Reference features users recognise, not your class names.
- Ticket numbers alone. Link them, but always describe the change in words.
Key takeaways
- Write for the user: describe effects, not implementation.
- Use standard categories: Added, Changed, Deprecated, Removed, Fixed, Security.
- Start every entry with a strong, consistent verb.
- Quantify improvements and be specific about fixes.
- Flag breaking changes loudly and include migration steps.
A good changelog is a small, repeated act of respect for your users’ time. Make it scannable and specific, and people will actually read it — and upgrade with confidence.