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.

Navigating Nuances: Refining Your Professional Voice

Let’s be honest – even experienced developers sometimes stumble when translating technical details into accessible language for a broader audience. A well-crafted changelog entry isn’t just about listing what changed; it’s about communicating why and the impact that change has. For non-native English speakers, this can feel particularly challenging due to subtle differences in phrasing and expectation around formality. Beyond simply using correct grammar, mastering the vocabulary of professional communication is key. Think about how you’d explain a complex situation to a colleague – that’s the tone you want to convey.

One common pitfall is over-reliance on overly formal language or technical jargon when aiming for clarity. Phrases like “utilization of” or “implementation of” can sound stilted and confusing, particularly for users who aren’t deeply involved in the development process. Instead, prioritize direct and concise statements. For example, instead of saying “The integration of the new API endpoint has been completed,” consider “We’ve added a new API endpoint to improve data access.” Similarly, when discussing breaking changes – vital to communicate clearly – avoid abstract descriptions like “system-wide modification.” Frame it in terms of user impact: “This update requires you to upgrade your application to version 2.5 to ensure continued functionality.”

Another area requiring attention is anticipating potential questions and proactively addressing them within the changelog entry itself. A good practice is to include a brief, layman’s explanation alongside technical details. This demonstrates foresight and reduces follow-up inquiries. Consider a Slack message during code review: “Hey team, just wanted to flag that this change introduces a minor dependency on lodash. It’s a common library, but users should be aware of it.” Or in a PR description, “This refactor improves performance by reducing unnecessary database queries – expect faster loading times.”

Finally, remember the importance of acknowledging potential issues. Transparency builds trust and shows you’re committed to providing a smooth user experience. Phrases like “Resolved an issue causing intermittent data loss” or “Corrected a bug that occasionally prevented users from completing transactions” are far more effective than vague statements about improvements. Focusing on resolution is key, always communicating the positive outcome of your work.