Documenting Breaking API Changes in Release Notes

Documenting Breaking Changes

Breaking changes are the most important part of any release notes because they directly affect users' ability to upgrade. Poor documentation of breaking changes leads to frustrated users, support tickets, and delayed adoption.

The Breaking Change Anatomy

Every breaking change entry should include:

1. What changed — the specific API, config, or behavior
2. Why it changed — the motivation (performance, security, consistency)
3. How to migrate — concrete steps or code changes needed
4. Before and after — code snippets showing the old and new way

Example

### BREAKING CHANGES

> **`authenticate()` now returns a Promise instead of a callback.**
>
> Before (v1.x):
> ```js
> client.authenticate(token, (err, user) => {
>   if (err) throw err;
>   console.log(user);
> });
> ```
>
> After (v2.0):
> ```js
> const user = await client.authenticate(token);
> console.log(user);
> ```
>
> **Migration:** Replace callback-based calls with async/await. If you
> need callback compatibility, wrap with `util.callbackify()`.

Grouping Strategy

For releases with many breaking changes, group them by area:

• API Changes — function signatures, return types
• Configuration — config file format, env variables
• Behavior — default values, error handling
• Dependencies — minimum versions, removed peer deps

Deprecation-First Approach

Ideally, breaking changes were deprecated first in a previous minor release. Reference that deprecation in the breaking change note so users who followed deprecation warnings are already prepared.