Breaking change
BRAY-king chaynj
A code change that causes existing functionality or integrations to stop working.
A breaking change is any modification that causes existing code, integrations, or workflows to fail. If your users wrote code that worked yesterday and your update makes it stop working today, that is a breaking change. It breaks the contract between your software and its consumers.
In API development, breaking changes include removing endpoints, changing response formats, renaming fields, or altering authentication methods. In libraries, they include removing public functions, changing function signatures, or altering default behavior. Even changing error messages can be a breaking change if consumers parse them programmatically.
Breaking changes are sometimes necessary. Technology evolves. Bad design decisions need correction. But how you handle them defines your reputation as a platform. Stripe is famous for maintaining backwards compatibility. They version their API by date and keep old versions running for years. Compare that with companies that push breaking changes without warning and wonder why developers stop building on their platform.
Examples
An API team removes a deprecated field.
Version 2 of the API removes the 'user_name' field, replaced by 'display_name' in version 1.5. The team gave 12 months of deprecation warnings, sent emails to all API consumers using the old field, and provided a migration guide. Still, 15% of integrations broke on launch day because developers ignored the warnings.
A library upgrade breaks a build pipeline.
A team upgrades React from 17 to 18. The new version changes how automatic batching works, and three components that relied on synchronous state updates start behaving differently. The team catches this in staging because their test suite covers those user flows. They fix the components before deploying to production.
A database schema change cascades through the system.
A developer renames the 'email' column to 'primary_email' in the users table. The ORM updates automatically, but three microservices that query the database directly break. Two third-party integrations that read the column via the API also fail. What seemed like a simple rename becomes a multi-team incident.
In practice
Read more on the blog
Frequently asked questions
How do you communicate breaking changes to developers?
Use multiple channels over a long timeline. Start with deprecation warnings in the API response headers and documentation at least 6 months before removal. Send direct emails to affected API consumers. Publish a migration guide with code examples. Post changelogs with clear 'BREAKING' labels. Stripe and Twilio are good models: they version aggressively and communicate proactively.
How does semantic versioning relate to breaking changes?
In semantic versioning (semver), the version number is MAJOR.MINOR.PATCH. A breaking change requires incrementing the MAJOR version. Going from 2.3.1 to 3.0.0 signals that something broke. Minor versions add features without breaking. Patches fix bugs without breaking. This convention lets developers understand the risk of upgrading at a glance.
Related terms
The ability of new software to work with older versions, data, or integrations without breaking them.
Application programming interface: a defined way for software programs to communicate with each other.
The structure and organization of a database, defining tables, columns, types, and relationships.
A scripted, versioned change to a database schema that evolves the data structure over time.
The process of releasing code to servers where users can access it.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.