A breaking change is a change that makes code that worked with the old version stop working with the new one. Semantic versioning says a major increment signals incompatible API changes, but the number is a promise by the maintainer, not a measurement, so behaviour changes can arrive in smaller releases.
What semver does and does not say
The Semantic Versioning specification defines three increments: major for incompatible API changes, minor for backward-compatible functionality, and patch for backward-compatible bug fixes. It also says versioning depends on a declared public API, and that major version zero is for initial development, where anything may change at any time.
Three consequences follow. A 0.y.z package can break you in a minor bump. A maintainer may judge a bug fix as non breaking when your code depended on the old behaviour. And not every package follows the rule.
Forms of breakage
| Type | Example | Caught by |
|---|---|---|
| Removed or renamed API | Function no longer exported | Compile, type check |
| Changed signature | New required argument | Compile, type check, tests |
| Changed default | Timeout or validation now stricter | Tests, if they cover it |
| Changed output format | Different date or error text | Tests, sometimes |
| Dropped platform support | Needs a newer runtime | Build, deploy |
| Changed transitive packages | A new dependency brings conflicts | Install, tests |
The middle rows are the dangerous ones, because they compile and may pass thin tests.
A five minute check on any fix PR
- Read the release notes between the two versions, not just the final one.
- Search your code for the changed or removed APIs named in them.
- Check the lockfile diff for added, removed and upgraded transitive packages.
- Confirm required checks include type checking and integration tests.
- Look at the runtime and platform requirements of the new version.
The reviewer checklist for fix PRs expands on this.
When no breaking change is documented
Absence of a note is weak evidence. Rely on your tests and a staged rollout for anything that sits on a critical path. A canary or phased deployment catches what a suite cannot.
Where Safeguard fits
Safeguard's autonomous remediation opens fix pull requests with every category on Manual by default, so a person judges breakage risk before merge, and policies and gates can require checks. You can run a free scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look at what information accompanies a proposed version change.
Quick check
Is a patch release always safe?
No. Patch means backward-compatible bug fixes by promise, but behaviour your code relied on can change.
Do major bumps always break my code?
No, but they are allowed to. Plan time to read notes and run tests.
Sources
Last reviewed: 19 October 2026.
