Avoid duplicating components when iterating on breaking changes
At some point the decision was made to duplicate gitlab-ui components while they are "in progress" and to rename them back (overwriting the old component) after they are completely implemented and their design has been approved. This was brought up in the CSS+GitLab UI working group meeting on 2019-10-09 (GitLab-internal link). It was independently brought up in Slack again (GitLab-internal link).
On a technical level:
-
<gl-button>
is being used in GitLab -
<gl-new-button>
is being worked on in gitlab-ui - after
<gl-new-button>
is finished and approved, it gets renamed to<gl-button>
- existing uses in GitLab will need to be adjusted
The same applies to <gl-dropdown>
and <gl-new-dropdown>
.
Reasoning behind the strategy
If I understand correctly, the strategy was first documented here: gitlab-foss#64873 (comment 200889394)
As far as I can tell, there were two main reasons for the duplication:
- new styling of the button component which could potentially break appearance of existing uses of
<gl-button>
in GitLab - new props of the button which would require refactoring the existing uses of
<gl-button>
in GitLab
From my understanding, buttons that are not instances of the <gl-button>
component (for example in HAML) are completely unaffected by this.
Reasoning why this strategy is not suitable for introducing new styling
If the new styling does not conflict with existing uses of <gl-button>
, it can directly be applied to the existing component. As far as I can tell, this scenario was deemed unlikely based on previous adventures with button styling.
If the new styling conflicts with existing uses of <gl-button>
, there is some work to be done in GitLab. The more styling is changed at once, the more places are affected, the higher are the chances that something breaks, and the bigger is the effort to fix it.
Reasoning why this strategy is not suitable for introducing new props
Adding new props which default to the old behavior can always be done on components without breaking existing uses. So this scenario does not justify duplication.
When changing the behavior / default value of an existing prop or removing an existing prop, changes will need to be made to existing uses in GitLab. Without duplicating the component, the changes in GitLab will need to be made when integrating the next gitlab-ui version. With duplicating the component, the changes in GitLab will need to be made when integrating the gitlab-ui version after replacing the old component. This means we get no benefit from duplicating. Even worse: While two components exist, new uses of the old components may be introduced in GitLab leading to a higher migration effort.
Side note: In theory it is possible to test each existing occurrence manually after adding the props to the new component and before renaming it.
However for components that are widely used, this approach does not scale. For example <gl-button>
is used in over 100 files:
grep -lr 'import.*GlButton' {ee/,}app/assets/javascripts | wc -l
112
Additional downsides of the approach
- Team members or contributors may miss the hint that for example
<gl-new-dropdown>
is not intended for use yet and get confused or have unintended behavior. - While two components exist, changes to the old component need to be copied over to the new one. This requires additional effort and delays the transition.