Breaking Change Policy: Managing API Evolution

WHY IT EXISTS Shared code, like a design system or an API, is a dependency for many teams. Without a policy, a single change by the maintainer can break numerous applications, creating widespread rework and eroding trust. A breaking change policy exists to make this inevitable evolution predictable and manageable for everyone involved.

THE MENTAL MODEL Think of a breaking change policy as the "rules of the road" for a shared library. It's a social contract between maintainers and consumers that says, "We promise not to suddenly move the steering wheel to the other side of the car. If we must, we'll give you months of warning, a clear migration path, and a very good reason." It's about managing trust and dependency risk, not just code.

HOW IT WORKS A policy first defines what constitutes a "breaking" change. This includes not just code that causes errors but also significant, disruptive visual or user experience changes. The process requires changes to be justified and communicated clearly. A key mechanism is deprecation: a feature is first marked as "deprecated," often with console warnings, to inform users of its impending removal. The actual breaking change is then implemented in a future major version release, giving consumers time to adapt their code.

WHEN TO USE IT Implement a breaking change policy for any shared asset with multiple consumers: public APIs, internal microservices, company-wide design systems, and open-source libraries. The more consumers you have, the more critical a clear policy becomes. It's the difference between a stable platform and a constant source of fire drills for dependent teams.

WHEN NOT TO USE IT A formal policy is overkill for a project in its very early, pre-release (e.g., version 0.x.y) stages where the API is in rapid flux and has no stable users. It's also less critical for a codebase used by a single, small team that can coordinate changes informally. The overhead isn't justified when the "blast radius" of a change is tiny and easily contained.

ONE CANONICAL EXAMPLE Wikimedia's Codex design system defines a breaking change as anything incompatible with its public API, including significant visual disruptions. For instance, changing a design token for line-height might not throw a compiler error, but if it causes page titles to get squished and overlap their containers, it's treated as a breaking change. Before removing a feature, they strongly recommend a deprecation period to warn users and give them time to migrate.