How to Write a Changelog Entry in English

A changelog entry is short by design, which makes precise word choice matter more, not less — a vague verb or an unclear scope can leave users confused about whether a change affects them. English changelogs follow fairly consistent conventions (a small set of standard verbs, consistent tense, clear categorization) that make them fast to scan. This guide covers the vocabulary and structure behind a well-written entry.

Key Vocabulary

Added — the standard verb for a new feature or capability that didn’t exist before, used in the past tense at the start of an entry. “Added: support for exporting reports as CSV files.”

Fixed — the standard verb for a resolved bug, used to describe what was broken and now works correctly. “Fixed: dashboard filters were not persisting after a page refresh.”

Changed — used for a modification to existing behavior that isn’t strictly a new feature or a bug fix, such as a UI adjustment or a default setting update. “Changed: default pagination size increased from 10 to 25 items per page.”

Deprecated — used to mark a feature that still works but is planned for removal, giving users advance notice before it becomes a breaking change. “Deprecated: the v1/users endpoint is deprecated and will be removed in a future release. Use v2/users instead.”

Breaking change — a change that requires users to update their own code, configuration, or workflow to keep working — the category that requires the clearest, most specific explanation. “Breaking change: the format parameter is now required on all export requests; previously it defaulted to JSON.”

Migration note — a short instruction accompanying a breaking change, telling users exactly what they need to do to adapt. “Migration note: update any calls to /export to explicitly include ?format=json if you relied on the previous default.”

Common Phrases

• “Added: [feature], allowing users to [benefit].”
• “Fixed: [issue] that caused [symptom] under [condition].”
• “Changed: [behavior] now [new behavior], previously [old behavior].”
• “Deprecated: [feature] will be removed in [version/date]; use [alternative] instead.”
• “Breaking change: [what changed]. Migration note: [what users need to do].”

Example Sentences

Writing a feature entry: “Added: bulk user invite via CSV upload, allowing admins to invite up to 500 users at once instead of adding them individually.”

Writing a bug fix entry: “Fixed: notifications were occasionally sent twice when a user updated their preferences within a few seconds of a previous update.”

Writing a breaking change entry with a migration note: “Breaking change: the apiKey field has been renamed to apiToken across all endpoints. Migration note: update any integration code referencing apiKey to use apiToken before upgrading — the old field name will return a 400 error starting in this version.”

Professional Tips

• Start every entry with a standard category verb (Added, Fixed, Changed, Deprecated, Removed) so readers can scan the changelog quickly without reading every sentence in full.
• For Fixed entries, describe the symptom the user actually experienced, not just the internal cause — “fixed a null pointer exception” means nothing to most users, but “fixed a crash when uploading files over 10MB” does.
• Every breaking change entry should include a migration note — a breaking change without instructions forces users to guess, which generates support tickets you could have prevented.
• Keep entries in past tense and consistent in structure throughout the changelog — mixing tenses or formats across entries makes the document feel unpolished even when the underlying work is solid.

Practice Exercise

1. Write an “Added” entry for a hypothetical new feature, including the user-facing benefit.
2. Write a “Fixed” entry describing a bug from the user’s perspective, not the internal cause.
3. Draft a breaking change entry with a migration note for a renamed API parameter.