breaking change
A change that makes existing users of a program or interface stop working until they change something too.
In more detail
Removing or renaming something users rely on, changing its behaviour, or making an optional field required are all breaking. Under semantic versioning a breaking change requires a new major version, and it should be marked clearly in commit messages and release notes.
Examples
Renaming a component prop such as isOutline is a breaking change; design systems deprecate first and ship a codemod.BREAKING CHANGE: clients must send Authorization on refresh.feat(auth)!: require a token on every session endpointA Kafka consumer reading v["id"] breaks when producers rename id.In Terraform: Under semantic versioning a breaking change needs a new major version and a migration note explaining what callers must change. Changing a module's internals while keeping its interface is not breaking, though renamed resources may need a moved block to avoid replacement.In this course: Contract tests catch accidental breaking changes. When one is intentional, version the contract and migrate consumers deliberately.Related terms
- backward compatibility — The property that a new version of an interface still works for clients written against the old one.
- API versioning — Giving an API contract a version so that incompatible changes can be released without breaking clients that use the old one.
- contract testing — Testing that an API’s real behaviour matches its written contract, and that its callers only rely on what the contract promises.
- semantic versioning — A version numbering scheme of three numbers, major.minor.patch, raised for breaking changes, new features and fixes respectively.
- deprecation — Marking a feature as outdated and scheduled for removal, while it still works, so users have time to move to its replacement.
- codemod — A script that rewrites source code automatically, for example renaming a deprecated prop across a whole codebase.
- Conventional Commits — A specification for commit subject lines of the form type(optional scope): description, so tools can read what kind of change each commit is.
- API contract — The written promise an API makes about its operations, inputs, outputs and errors, which callers rely on while the code behind it changes.
- wire format — The exact shape data takes when it travels between programs, such as the field names and types of a JSON body.
- schema evolution — Changing the structure of your data over time while keeping existing producers and consumers working.
- expand-and-contract — A way to change a live database in safe steps: add the new structure, move data and code to it, then remove the old structure.
- module interface — The variables a module accepts and the outputs it publishes, which together are everything a caller may rely on.
- changelog — A file or page listing the notable changes in each release of a project, newest first.
Taught in
- Versioning APIs — Modern API Architecture: REST, GraphQL & gRPC
- Contract Testing — Modern API Architecture: REST, GraphQL & gRPC
- Design Systems Architecture: Foundations, Layers & Taxonomy — Design Systems & Component Engineering
- Visual Regression Testing: Playwright & Snapshot Differencing — Design Systems & Component Engineering
- System Governance: Changesets, Semantic Versioning & Deprecation — Design Systems & Component Engineering
- Conventional Commits — Advanced Git Internals & Distributed Workflows
- Serialization And JSON — Modern Java: Virtual Threads & High-Throughput Services
- Controllers And Routing — Modern Java: Virtual Threads & High-Throughput Services
- Implementing An OpenAPI Contract — Modern Java: Virtual Threads & High-Throughput Services
- Compatibility Modes — Apache Kafka & Event Streaming
- Evolving An Event Without Breaking Consumers — Apache Kafka & Event Streaming
- Versioning And Pinning Modules — Infrastructure as Code with Terraform
- Contract Testing Between Services — Automated Testing, TDD & Quality Engineering