Versioning and Deprecation
How the system changes without breaking the products built on it.
Definition
Versioning communicates the nature of a change; deprecation is the process of retiring something with enough notice and support that consumers can migrate. Both are what allow a system to evolve at all.
Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.
What counts as breaking
- Removing or renaming a prop, a token or a component.
- Changing default behaviour, which is breaking even when the API is unchanged.
- Visual changes large enough to alter layout, since consumers build around dimensions.
- Changing keyboard behaviour or accessible names, which breaks tests and user habits.
A deprecation that works
- 1
Announce with a reason
Say what is being retired, why, and what replaces it.
- 2
Ship the replacement first
Never deprecate before the alternative exists and is documented.
- 3
Warn in place
Console warnings in development, and a notice on the documentation page.
- 4
Provide migration tooling
A codemod, or at minimum a precise before-and-after guide.
- 5
Give a real notice period
Long enough for teams to fit it into a planning cycle, and state the removal date.
- 6
Remove
In a major version, not a minor one.
Continue from here
Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.
Principles behind this
The reasoning this solution is an application of.
- Loss AversionCognitive bias
- Status Quo BiasCognitive bias
Practical example
A worked decision where this was the deciding factor.
Short definition
The one-paragraph version, for when that is all you need.
- DeprecationTerm
- Feature FlagTerm
- Semantic VersioningTerm
- Single Source of TruthTerm
Related concept
Connected closely enough to change how you apply this.
- Component API DesignDesign system
- Design System AdoptionDesign system
- Design System DocumentationDesign system
- Design System GovernanceDesign system