Document process for rolling out breaking changes in components
Sometimes we need to make breaking changes to components, either literally in their API, or in their implicit styling contract.
The best way to roll these changes out isn't immediately obvious. Trying to migrate all uses at once can get bogged down with edge cases and too much manual testing (e.g., see gitlab!28356 (closed)). We've tried adding GlNew*
components (e.g., GlNewButton
and GlNewDropdown
), although that's caused some confusion in the past[citation needed].
It seems that the current-best approach is to rename the old version of the component GlDeprecatedFoo
, and make the new version available as GlFoo
. Then, integration MRs need only contain essentially:
- import { GlFoo } from '@gitlab/ui';
+ import { GlDeprecatedFoo as GlFoo } from '@gitlab/ui';
Then, each usage can be updated iteratively, case-by-case, rather than all at once.
There's a detailed example of this sort of approach written in #673 (closed), if you ignore the GlNew*
parts.
If the above is a solid means of rolling out breaking changes to components, then it would be useful to have it documented.