How to Write Release Notes for a Major API Version Bump
It is Tuesday morning, and your continuous integration pipeline is red.
Your team relies on a third-party billing API. Overnight, the provider shipped a v2.0 release. They deprecated the old endpoints, changed the authentication flow, and altered the shape of the user object. You open their developer portal, hoping for a migration guide.
Instead, you find a single paragraph announcing that the new version features "a transformed identity model" and "best-in-class performance."
You do not care about their identity model. You care that your checkout flow is currently rejecting payments.
This is the core tension of a major version bump. To the provider, it is a technical milestone and a marketing opportunity. To the consumer, it is an uninvited disruption. The release notes are the only artifact standing between a frustrated developer and a decision to rip out your API entirely. Poor release notes during a breaking change create support load, churn risk, and reputation damage that lasts long after the technical transition is complete.
If you are writing the release notes for a major version bump, you are not writing a product announcement. You are writing an operational blueprint.
The Anatomy of a Breaking Change
Start with the impact and the timeline.
Users need to know immediately what broke, when the old version sunsets, and what the migration path will cost them in engineering time. This information goes first. It does not go under the feature marketing.
Organize the breaking changes by user impact, not by your internal engineering logic. The way your team categorized the work in Jira is not the way your users experience the consequences.
Every breaking change entry needs four things: what broke, why it broke, the old behavior, and the new behavior. If any of those four are missing, the note is incomplete. A developer triaging the impact on their integration should be able to read a single entry and know whether they need to act.
Include a dedicated section for what stays the same. During a major version transition, users assume everything is different. Explicitly listing what did not break—authentication flows, rate limits, webhook signatures, data formats—reduces the perceived migration risk. It gives users confidence that the bump is scoped and planned, not chaotic. This section costs you almost nothing to write and saves your support team a significant volume of "does X still work?" tickets.
Why Did You Do This to Us?
Explain the "why" behind the breaking changes.
Users tolerate necessary breaking changes far better than arbitrary ones. Tom Preston-Werner, who wrote the original Semantic Versioning spec, made this point directly: each breaking change means manual code modifications for some users, and if you break the API too frequently without clear justification, you risk fatiguing your users. A single sentence explaining the reason reduces frustration and builds trust.
Maybe you removed a parameter because it was a security vulnerability. Maybe you changed a data structure to align with an industry standard. Maybe you dropped support for an old endpoint to remove technical debt that was slowing down the entire platform.
Tell them. You do not need to write a thesis, but you do need to justify the disruption. If you cannot explain why a breaking change was necessary in one sentence, that is worth reflecting on before shipping it.
The Migration Path Is the Product
Provide before-and-after code examples for every breaking change that affects the API surface.
Not pseudocode. Real, compilable examples in the languages your users actually work in. Show the exact JSON payload from v1 next to the exact JSON payload from v2. Include the error messages users might encounter if they fail to migrate correctly, and explain how to resolve them. When a developer hits a 400 Bad Request during migration, they will search your release notes for the exact error string. If it is not there, they will open a support ticket.
Release notes for a major version bump should go out in stages, not all at once.
Consider early preview notes for beta users. Publish detailed migration guides 60 to 90 days before the forced cutover. The final launch announcement should link to the full technical notes rather than trying to replace them. The launch announcement is for awareness and framing; the migration guide is the real operational document.
Use versioned documentation URLs. Keep the old version docs online and accessible for as long as the version is supported. Users migrating late, or troubleshooting a regression, need to compare old and new behavior side by side. Sunsetting the v1 docs the day v2 launches creates unnecessary support load. GitHub, for example, announces breaking changes at least three months before making changes to their GraphQL schema, giving integrators time to plan. The pattern is worth copying: a specific date, a specific scope, and a clear migration path. "We will remove this endpoint eventually" gives an engineering manager nothing except a reason to procrastinate until something breaks.
The Changelog Needs a Changelog
Before publishing, run the release notes past actual API users in a controlled preview.
Ask a private beta group or select enterprise customers a simple question: "Can you build a migration plan from this document alone, or do you need to ask us questions?"
If they need to ask questions, the notes are incomplete. This is not a subjective quality bar—it is a functional one. The document either enables independent migration planning or it does not.
Include a changelog of the changelog. If breaking changes get discovered post-launch, or if migration guidance gets updated based on early feedback, version the release notes themselves and surface what changed. Users who read the notes two weeks ago need to know if new guidance has been added. A document that silently changes after publication is almost as bad as a document that was wrong to begin with.
Major version bumps are where API providers reveal whether they understand their users' constraints. The release notes are not a formality. They are the blueprint users rely on to decide whether migrating is feasible, whether your API is still worth the dependency risk, and whether they trust you to manage future breaking changes responsibly.
Maintaining this level of structural consistency and completeness across a large API surface is an operational challenge. It is why teams use Doc Holiday to generate breaking change documentation directly from version control and API definitions. The system generates the structured output—the exact diffs, the before-and-after payloads, the removed fields—and surfaces it for technical review. It provides the baseline, so skilled oversight can focus on clarity, context, and the user-facing polish that makes the difference between a migration guide and a support ticket.
