Breaking Change
A change to a system that makes existing clients fail or behave differently unless they are modified.
Also known as: Breaking Changes, Incompatible Change, Backward-Incompatible Change, API Break
Category: Software Development
Tags: software-development, software-engineering, compatibility, api-design, maintainability, change-management
Explanation
A breaking change is any modification that forces the people who depend on your system to do work they didn't plan. Their code stops compiling, their requests start failing, or, worst of all, everything still runs but produces different results.
**Kinds of breaking changes**:
- **Removals and renames**: A field, function, endpoint or option disappears
- **Signature changes**: Different types, a new mandatory parameter
- **Stricter input**: You start rejecting requests that you used to accept
- **Different output**: A changed format, new enum values that clients don't expect, another default sort order
- **Semantic changes**: Same name, same shape, different meaning. A value that was in seconds is now in milliseconds
- **Non-functional changes**: Slower responses, lower rate limits, different timing or error messages
**The uncomfortable part**:
You don't get to decide what is breaking. Your users do. With enough users, somebody depends on every observable behavior, including the ones you never documented (see Hyrum's Law). A bug fix is a breaking change for whoever relied on the bug.
**How to avoid them**:
- **Prefer additive changes**: Add new things next to the old ones
- **Use parallel change**: Expand, migrate, contract
- **Be strict from the start**: You can loosen a rule later without breaking anyone. Tightening it is a breaking change
- **Keep the surface small**: Whatever you don't expose, you can change freely
- **Know your consumers**: Consumer-driven contracts and usage telemetry tell you what is really in use
**How to make them when you must**:
- Signal them with a new major version (see Semantic Versioning)
- Announce early, document the migration, give a timeline (see Deprecation)
- Provide tooling where you can: automated migrations beat migration guides
- Batch them. One painful upgrade is better than ten
**The trade-off**:
Never breaking anything means carrying every past mistake forever. Breaking things often means nobody trusts you enough to build on you. Mature projects break rarely, deliberately and loudly.
Related Concepts
← Back to all concepts