End-to-end process for a Modal props API break

WHAT THIS TESTS This evaluates the complete lifecycle of a breaking change, from why it is needed through to broad adoption, on a high-impact component.

A GOOD ANSWER COVERS Start by validating the need: what problem with the current Modal props forces a break, and is there a non-breaking alternative. Gather input from consumers, then design the new API and circulate an RFC or proposal so affected teams can react before code lands. Implement additively where possible: support both the old and new props, mapping old to new internally, and emit deprecation warnings for the old shape. Release the change as a major version per semver. Provide a codemod to auto-migrate common usage and a migration guide with before-and-after examples. Communicate early and repeatedly through changelog, release notes, direct outreach, and a clear removal timeline. Maintain an adoption dashboard tracking who still uses the old props, support stragglers, and only remove the deprecated API in a later major once adoption is high.

COMMON WRONG ANSWERS Jumping to a hard swap with no rationale or RFC. No deprecation overlap. No codemod or guide. One-shot communication. Shipping the break as a minor.

LIKELY FOLLOW-UPS When is a parallel new component better than breaking the existing one? How long should the overlap last? How do you handle teams that cannot upgrade?

ONE CONCRETE EXAMPLE The Modal moves from onClose plus isOpen booleans to a single open-state controller prop. You publish an RFC, then version 5.0.0 supports both shapes with the old one deprecated. A codemod rewrites common usage and a guide covers the rest. You announce a removal date, track remaining old-prop usage, and version 6.0.0 finally removes the legacy props.