Breaking change
A breaking change is any change to a published interface (API endpoint, library function signature, CLI flag, configuration key) that requires consumer code or configuration changes to keep working. Breaking changes bump the MAJOR version under semver and typically require deprecation notice, migration guide, and a parallel-support window before old behaviour is removed.
Treating a change as breaking is a deliberate choice with downstream cost: every consumer must update. The discipline of avoiding gratuitous breaks — by extending rather than replacing, by adding new endpoints rather than reshaping existing, by deprecating-then-removing rather than removing-then-apologising — is what distinguishes mature libraries from young ones. When a break is necessary, the playbook: announce in N+1, deprecate in N, support both for at least one release cycle, remove in N+2 with a migration tool. Breaking changes done well are non-events for consumers; done badly, they are why teams pin tightly and never upgrade.
Discussed in our use-cases
ICP-targeted pages where breaking change is part of the framing.
Related terms
- Semantic versioning (semver)
Semantic versioning is the package-versioning convention MAJOR.
- Deprecation window
A deprecation window is the period between announcing that a feature will be removed and actually removing it — typically 3-12 months for SaaS APIs, longer for libraries.
- Lockfile
A lockfile records the exact resolved version of every package in a dependency tree — direct and transitive — so any subsequent install reproduces the same versions.