How to Write a Changelog in English

A changelog written from commit messages reads like it was written for the author, not the reader — a good changelog is written for someone deciding whether to upgrade, which means translating internal implementation detail into user-relevant impact.

Key Vocabulary

Added / Changed / Fixed / Removed — the standard categorization headers, following conventions like Keep a Changelog, that group entries by what kind of change they represent, letting a reader scan for the category they actually care about. “Sort these entries under Added, Changed, Fixed, and Removed instead of one flat list — someone upgrading mainly cares whether anything was removed or changed in a breaking way, and flat lists make that hard to find quickly.”

Breaking change — a change that requires the consumer to modify their own code or configuration to keep working, which needs to be called out explicitly and prominently, not buried among routine fixes. “This needs a clear breaking change callout at the top, not buried in the Changed section — renaming this required config field means every existing user’s config breaks silently until they update it, and that deserves visibility.”

User-relevant impact (not implementation detail) — describing a change in terms of what the user experiences or needs to do differently, rather than describing internal code changes that don’t affect how the software is used. “Rewrite this entry — ‘refactored the internal caching layer’ describes implementation detail nobody using the library cares about. If it improved response times, say that: ‘improved average response time by 30% for repeated queries.’”

Migration note — a short explanation, sometimes with a code example, telling users exactly what to change in their own code to accommodate a breaking change, included directly in the changelog entry rather than in a separate document users might miss. “Add a migration note right under the breaking change entry — show the old function call and the new one side by side, so someone upgrading doesn’t have to go dig through documentation to figure out what changed.”

Common Phrases

• “Should this go under Added, Changed, or Fixed?”
• “Is this actually a breaking change, or is it backward compatible?”
• “Does this entry describe user-relevant impact, or is it just implementation detail?”
• “Does this breaking change need a migration note with an example?”
• “Would someone scanning this changelog understand what they need to do before upgrading?”

Example Sentences

Writing a well-categorized entry: ”### Fixed — Corrected an issue where date filters using a custom timezone returned results one day off near midnight. This affected any query using the timezone parameter with a non-UTC value.”

Calling out a breaking change clearly: ”### Breaking Change — The fetchUser(id) function now returns a Promise instead of accepting a callback. Existing callback-based calls will throw a deprecation error. See the migration note below for the updated syntax.”

Writing a migration note: “Migration note: replace fetchUser(id, callback) with const user = await fetchUser(id). If you can’t use async/await in this context, wrap the call in fetchUser(id).then(callback) instead.”

Professional Tips

• Organize entries under standard headers like Added, Changed, Fixed, and Removed — a consistent structure lets readers scan for exactly the category they need instead of reading the whole log.
• Never bury a breaking change among routine entries — give it its own prominent section or a clear, unmissable label at the top of the relevant version.
• Translate every entry into user-relevant impact, not implementation detail — if a change doesn’t affect how the software is used or its behavior, it usually doesn’t belong in a user-facing changelog at all.
• Include a concrete migration note with every breaking change — showing the exact before-and-after code saves every single user from having to work it out themselves.

Practice Exercise

1. Rewrite an implementation-detail-focused changelog entry to describe user-relevant impact instead.
2. Draft a breaking change callout for a hypothetical renamed API parameter.
3. Write a migration note showing before-and-after code for that breaking change.

Navigating Nuances: Language Support for Non-Native Developers

Writing a changelog effectively isn’t just about listing what changed; it’s about communicating those changes clearly and concisely to your team. For developers who are learning professional English, the subtleties of phrasing – particularly in technical documentation – can be incredibly challenging. It goes far beyond simply translating words; it’s about adopting the accepted conventions for how engineers discuss software updates within a collaborative environment. Let’s look at some common pitfalls and strategies to help you build confidence and ensure your changelog is understood by everyone.

One frequent issue is using overly literal translations. For example, if you’re documenting a bug fix in your native language, the phrase might directly translate to something like “Resolved problem with incorrect calculation.” In English, that sounds clunky and doesn’t convey the impact of the change. Instead, aim for phrasing like “Fixed a calculation error leading to inaccurate results,” or even better, “Corrected a bug in the calculation module resulting in erroneous data.” The latter is more professional, precise, and immediately understandable. Pay attention to verb tenses – consistent use of the present perfect (“we have fixed”) versus the simple past (“we fixed”) can significantly impact clarity.

Another area needing careful consideration is “breaking changes.” Directly translating phrases like “major disruption” or “significant alteration” might feel appropriate in some contexts, but they lack precision. A better approach is to describe what broke and how it affects users or other parts of the system. For instance, instead of stating “This update introduces a breaking change,” you’d say: “Removed support for legacy API version 1.0. This requires developers to migrate their applications to use version 2.0.” Adding a brief explanation of why the change was made – even if it’s just “to improve performance” – further enhances understanding.

Finally, consider how your changelog appears within team communication channels. A concise, well-written entry is ideal for a PR description, but you might need to adapt your language depending on the context. For example, a quick Slack message summarizing a change could be: “Fixed a critical bug in the user authentication flow. Users may experience intermittent login issues – please test thoroughly.” Notice how it’s direct and prioritizes immediate impact. Remember, clarity and precision are paramount; avoid jargon unless absolutely necessary and always explain its purpose.