Releasing a breaking Button change with SemVer

WHAT THIS TESTS This evaluates whether you respect the SemVer contract and treat consumers as a real audience, providing the artifacts and process that let them upgrade safely rather than just bumping a number.

A GOOD ANSWER COVERS Under semantic versioning, an incompatible API change requires incrementing the major version, for example from 2.x to 3.0.0. The reasoning is that consumers pin ranges like caret 2 expecting no breakage, so a breaking change must move the major. Around the release you create artifacts. A changelog entry clearly marks the breaking change under that version. A migration guide shows before and after code, lists removed or renamed props, and explains replacements. Where feasible, soften the break: in a prior minor release, deprecate the old prop with a runtime console warning and document the replacement, then remove it in the major. Optionally ship a codemod script so consumers can auto-migrate. Announce the release through your normal channels and consider supporting the previous major for a window.

COMMON WRONG ANSWERS Releasing a breaking change as a minor or patch violates SemVer and silently breaks consumers on auto-update. Removing a prop with no deprecation period or warning gives no migration runway. Skipping the migration guide leaves teams to reverse-engineer the change. Bumping major but documenting nothing is almost as bad.

LIKELY FOLLOW-UPS What exactly counts as breaking, including changed defaults and removed props? How long do you support the old major? How do automated tools like Changesets or semantic-release infer the bump from commit messages? When is a visual change breaking? How do you handle a breaking change that is forced by a security fix?

ONE CONCRETE EXAMPLE The Button drops its deprecated variant prop in favor of intent. In version 2.7 you keep variant working but log a deprecation warning pointing to intent. In version 3.0 you remove variant, ship a CHANGELOG noting the breaking change, a migration guide mapping each old variant value to an intent value, and a codemod that rewrites usages, so consumers upgrade in minutes.