What Is Breaking Change

A breaking change is any modification to a design system that prevents existing consumer code from working correctly after an upgrade. Breaking changes require consumers to modify their implementations to accommodate the change, making them fundamentally different from backwards-compatible updates. Recognizing breaking changes is essential for proper versioning and consumer communication.

What Defines a Breaking Change

Breaking changes fundamentally alter the contract between a design system and its consumers. This contract encompasses the programmatic API, expected behaviors, visual output agreements, and integration patterns. When any part of this contract changes in a way that invalidates existing consumer implementations, a breaking change has occurred.

The impact of breaking changes varies from compilation errors to subtle behavioral differences. Some breaking changes are immediately obvious, such as removing a component entirely. Others are more subtle, such as changing how a component handles edge cases. Both types require consumer attention and potentially code modifications.

How Breaking Changes Work

Breaking changes manifest through various types of modifications to a design system. Understanding these categories helps teams identify breaking changes during development and code review.

API removal constitutes the most straightforward breaking change. Removing a component, prop, event, or export prevents consumer code from referencing that API. The consumer’s code fails to compile or throws runtime errors until updated to remove the deleted reference.

API modification includes renaming props, changing type signatures, or altering function parameters. Consumers using the previous API must update their code to match the new interface. TypeScript projects typically catch these at compile time, while JavaScript projects may encounter runtime errors.

Behavioral changes affect how components function without necessarily changing the API signature. Changing default values, altering event timing, modifying DOM structure, or adjusting error handling can all break consumer code that depends on the previous behavior.

Dependency changes can propagate breaking changes from underlying libraries. Major version bumps in peer dependencies may introduce incompatibilities. Changes to build output formats or supported runtime environments similarly affect consumers.

Key Considerations

• Breaking changes require major version increments in semantic versioning
• Deprecation periods before breaking changes give consumers time to prepare
• Migration guides help consumers update their code efficiently
• Codemods can automate straightforward code transformations
• Communication channels should announce breaking changes prominently

Common Questions

How can teams minimize breaking changes?

Design system teams can reduce breaking change frequency through careful API design and additive development patterns. Designing flexible APIs from the start reduces the need for later modifications. Adding new optional parameters rather than changing existing ones maintains backwards compatibility.

When breaking changes become necessary, batching them into planned major releases reduces upgrade frequency. Teams can also provide parallel APIs during transition periods, keeping old APIs functional while introducing new ones. Clear deprecation warnings guide consumers toward updated patterns before old APIs are removed.

What is the difference between a breaking change and a bug fix?

The distinction can be subtle when a bug fix changes behavior that consumers unintentionally depend upon. Strictly speaking, fixing incorrect behavior aligns the implementation with documented intent, making it not breaking. However, consumers may have worked around the bug, making the fix breaking from their perspective.

Teams often make pragmatic decisions based on how widely the bug was exploited versus its severity. Critical bugs may warrant immediate fixes regardless of consumer impact. Minor bugs with widespread workarounds may be deferred to major versions. Communication about bug fixes and their potential impact helps consumers prepare.

Summary

Breaking changes modify design system contracts in ways that require consumer code updates. They encompass API removal, API modification, behavioral changes, and dependency updates. Proper identification and communication of breaking changes enables accurate versioning and helps consumers plan their upgrade strategies effectively.