Technical and comms plan for a Button break

What's really being asked

This checks that you treat a breaking change as both a technical migration and a coordination problem across many teams.

The full answer

On the technical side, prefer an additive rollout: introduce the new API while the old one still works, mark the old path deprecated with build or runtime warnings, and reserve removal for a future major. Bump the major version per semver. Write a codemod so most consumers migrate automatically, and a migration guide with concrete before-and-after snippets. On the communication side, announce early and through several channels: changelog, release notes, a dedicated message to consuming teams, and optional office hours or a support thread. Publish a clear deprecation timeline with a removal date, and maintain an adoption dashboard showing who still uses the old API so you can nudge stragglers. Remove the deprecated path only once adoption is high, in the next major.

The mistakes people make

Nailing the code but ignoring communication. A single announcement treated as enough. No deprecation window. No tooling to ease migration. Shipping the break as a minor version.

What usually comes next

How do you handle a team that misses the deadline? How long should the deprecation window be? How do you measure adoption automatically?

A concrete example

The Button drops a deprecated size prop in favor of a new scale prop. Version 7.0.0 supports both, with size emitting a deprecation warning. You publish a codemod, a migration guide, and announce two sprints ahead with a removal date. A dashboard tracks remaining size usage. Once it nears zero, version 8.0.0 removes it.