Breaking Change
A breaking change is a change that is not backward compatible.
It causes previously working integrations, code, configurations, or workflows to stop working unless users adapt to the new behavior.
What it does
A breaking change alters compatibility expectations.
It is commonly used to describe changes that:
- Remove or rename existing behavior
- Change expected inputs or outputs
- Require different configuration or usage
- Invalidate older integrations or assumptions
- Force downstream users to update something on their side
Core concepts
Compatibility impact
The key idea is not whether the change is large or small.
The key idea is whether existing consumers can keep working without adjustment.
Versioning signal
In SemVer, breaking changes are what justify increasing the major version.
Release risk
Breaking changes usually require clearer communication, better documentation, and stronger QA because they affect adopters directly.
Common use cases
- API changes
- Library or plugin behavior changes
- Removed configuration options
- Changed data formats
- Platform upgrades that invalidate old assumptions
Practical notes
- A breaking change can be technically small but operationally significant.
- Good teams document breaking changes clearly in release notes and upgrade guides.
- In plugin ecosystems such as WordPress, breaking changes can be especially disruptive when many sites depend on stable behavior.
- Breaking changes are one of the main reasons teams pay attention to versioning and SemVer.
Sources Used
Frequently Asked Questions
Is every bug fix a breaking change?
No. A fix is only breaking if it changes behavior in a way that existing users or systems can no longer rely on without adjustment.
Do breaking changes always require a major version bump?
Under strict SemVer, yes.
Why are breaking changes important?
Because they affect upgrade risk and can force users to change code, configuration, or workflows.