Say it like this
- This update introduces breaking changes
- We need to avoid breaking changes in this release
- That's a breaking change to the public API
Use it at work
Warning others
- Heads-up: this PR has a breaking change to the API.
- This is a breaking change, so mobile needs to update first.
Planning a release
- Let's save breaking changes for version 3.
- We'll list breaking changes in the release notes.
In a code review
- Renaming this field is a breaking change.
- Can we add the new field without a breaking change?
Don't say this
A breaking change is not the action itself but the consequence; not all bug fixes cause breaking changes.
Practice
Try it
4 quick exercises
1. Your team changed a function signature. How do you describe this to leadership?
2. Removing the old authentication method without a deprecation period would be a _______ that affects all our clients.
3. Which sentence uses the term incorrectly?
4. Rewrite this using proper tech terminology: 'We removed a feature that people were using, and now their code will not work anymore.'
Say it out loud
Phrase 1 of 3
"This update introduces breaking changes"
We don't save your recording. The word check uses your browser's speech recognition.
More about breaking change
Real examples(3)
- in a standup
"I wanted to warn everyone that the database schema changes in version 3.0 will be breaking changes for our service."
- in a code review
"Removing this parameter from the function is a breaking change; we should deprecate it first instead."
- in a team meeting
"Before we merge this PR, we need to discuss whether these changes constitute breaking changes and plan accordingly."
More mistakes(1)
Handle with care. Do not confuse with simply fixing bugs or making updates. A breaking change specifically affects users or systems that depend on your code.
- ✕This breaking change will improve performance.✓This breaking change will improve performance, so we should increment the major version.
Breaking changes should always be explicitly acknowledged and documented, not presented casually as improvements.
Other forms(2)
- breaking change noun
"The removal of the deprecated endpoint is a breaking change."
- breaking changes (plural) noun
"Version 2.0 contains several breaking changes that require user migration."
Often used with(5)
- introduce a breaking change · To make a modification that is incompatible with previous versions
- avoid breaking changes · To prevent modifications that would break dependent code
- major breaking changes · Significant incompatible updates that affect many users
- breaking change in the API · An incompatible modification to the application programming interface
- breaking change documentation · Written guidance explaining what changed and how to update dependent code
Similar words(2)
- backward incompatible change · More formal term for the same concept; emphasizes that old code will not work
- incompatible update · Slightly less technical; focuses on the inability of versions to work together
Opposites(2)
- backward compatible change
- non-breaking change
Questions(4)
- What exactly is a breaking change in software?
- A breaking change is any modification to software that makes existing code stop working or behave unexpectedly. This includes removing functions, changing how functions work, altering data formats, or modifying API endpoints. The key characteristic is that users of your code will need to update their own code to continue using your software.
- How do you communicate breaking changes to users?
- Breaking changes should be clearly documented in release notes, changelog entries, and migration guides. Many teams use semantic versioning to signal breaking changes with a major version increment. You should also provide a deprecation period when possible, warning users before removing functionality entirely.
- How is breaking change different from a bug fix?
- A bug fix corrects incorrect behavior to match the intended design, and users usually expect this. A breaking change removes or fundamentally alters working functionality, forcing users to adapt. Some bug fixes can inadvertently be breaking changes if users have written code that depends on the buggy behavior.
- Why do teams want to avoid breaking changes?
- Breaking changes force all downstream users and systems to update their code, which can be expensive, time-consuming, and risky. Multiple projects might depend on your code, and coordinating updates across many teams is complex. For this reason, teams often prefer deprecation periods and backward-compatible solutions.
