# What is Breaking Change?

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](/glossary/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](/glossary/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](/blog/how-to-write-release-notes/).

## Related terms

- [Conventional Commits](/glossary/conventional-commits/)
- [Deprecation Policy](/glossary/deprecation-policy/)
- [Changelog](/glossary/changelog/)
- [Release Notes](/glossary/release-notes/)

Deeper guide: [How to write release notes users actually read](/blog/how-to-write-release-notes/)

Category: Release Engineering
Last reviewed: 2026-05-28