Structuring release notes for breaking API changes

WHAT THIS TESTS: It evaluates whether you can apply documentation structure and rhetoric to keep developers from churning when they are forced through breaking changes they did not choose.

A GOOD ANSWER COVERS: Lead with a short summary and the why, because developers tolerate breakage when the benefit is clear and stated up front. Visibly segregate breaking changes from additions and fixes, ideally a dedicated, scannable section at the top rather than buried in chronological order. For each breaking change, state what changed, why, the impact, and a concrete migration step with before-and-after code snippets. Provide a deprecation timeline and, where possible, an overlap window where the old behavior still works behind a flag or an older version, giving teams time to migrate safely. Link to a standalone migration guide and an automated codemod if one exists. Stylistically, use plain language, second person, and empathetic framing that acknowledges the cost while emphasizing the path forward.

COMMON WRONG ANSWERS: A single chronological dump mixing breaking and trivial changes. Marketing-speak that hides or minimizes the breakage. Listing what changed without telling users how to fix their own code. Providing no timeline, which forces an immediate scramble and maximizes frustration.

LIKELY FOLLOW-UPS: How do you version this so the breakage is signaled, for example through semantic versioning. How do you communicate proactively before the release lands. How do you handle large customers who cannot migrate quickly. Should you ship a codemod to automate the mechanical parts of the change.

ONE CONCRETE EXAMPLE: For a renamed authentication endpoint, the notes open with 'v3 unifies auth under one endpoint for fewer round-trips,' then a Breaking Changes section shows the old call beside the new one, gives a three-line migration step, notes that the old endpoint stays available until a stated date, and links the full migration guide. A developer can then act in minutes instead of guessing what broke and why their integration suddenly fails.