What is Breaking Change?
Last reviewed May 28, 2026
A breaking change is a software change that requires the people consuming your API, library, or product to update their code, configuration, or workflow to keep working — removing a public method, changing a default behavior, requiring a new authentication header. Breaking changes are typically called out explicitly in release notes (often with their own section) and trigger a major version bump under semantic versioning. Mishandled breaking changes are the fastest route to losing customer trust.
Example
Removing a deprecated /v1/users endpoint after a 12-month sunset period is a breaking change — every integrator still calling /v1/users will start receiving 404s the moment the change ships. Changing the default value of a config flag from true to false, or requiring a new header on every API request, are also breaking changes even if technically backward-compatible in code.
Why it matters
Breaking changes are inevitable as products evolve, but how you handle them is what builds or burns trust. Teams that announce breakages weeks ahead, list every one in a dedicated section of release notes, and provide migration steps keep their integrators happy. Teams that ship breakages buried in a "minor improvements" bullet on release day get angry tickets, churn, and bad word of mouth in dev communities.
More context
The hard part isn't deciding what's a breaking change — it's the discipline of communicating about it well.
A few patterns separate the products that handle breaking changes well from the ones that don't:
Dedicated section in release notes. A breaking change that's buried in a bullet of "improvements" gets missed. Give it its own section with a heading like "Breaking changes" or "Migration required" so anyone scanning the release sees it immediately.
Advance notice. Announce breaking changes in the release where the affected feature is deprecated, not in the release where it's removed. Stripe's API model is a good reference here — features are marked deprecated, supported for a long sunset window (often 12+ months), and announced in every interim release until removal.
Migration steps in the release notes themselves. If the fix is "rename oldField to newField," put that in the release notes. Don't make readers click through to docs to figure out what to change. The lowest-friction breaking change is one where the fix is right there in the announcement.
Use the BREAKING CHANGE: footer in your commits. If you're following Conventional Commits, the footer triggers a major-version bump under semantic versioning automatically — and tools like Herald can surface every commit with that footer in a dedicated breaking-changes section when drafting the release.
The intersection of breaking changes, deprecation policy, and customer-facing communication is where developer-tool reputations get built or lost. For the practical "how to communicate this well" piece, see the release notes guide.
Related terms
Want to go deeper? Read How to write release notes users actually read.