Skip to content

Latest commit

 

History

History
64 lines (52 loc) · 3.26 KB

breaking_changes_to_components.md

File metadata and controls

64 lines (52 loc) · 3.26 KB

Introducing and rolling out breaking changes to components

There is currently no standard approach for rolling out breaking changes in GitLab UI components to projects that consume them. Various approaches have been tried in the past, and some have worked better than others. Whatever the approach is, it can get tricky when a component is used in many places in a large codebase, like GitLab.

Here is an outline of an approach that has worked reasonably well. Suppose the component to receive the breaking changes is called GlFoo:

  1. Introduce a minor version change to GitLab UI that simply re-exports the given component, say GlFoo, under an additional name, GlDeprecatedFoo. The same GlFoo export is still available.

    For example, in index.js:

    - export { default as GlFoo } from './src/components/base/foo/foo.vue';
+ export { default as GlFoo, default as GlDeprecatedFoo } from './src/components/base/foo/foo.vue';

  2. Open integration MRs with projects that consume GitLab UI (e.g., GitLab) that bump @gitlab/ui to the new minor version, and change all existing imports of GlFoo to GlDeprecatedFoo, but alias it back to GlFoo.

    For example:

    - import { GlFoo } from '@gitlab/ui';
+ import { GlDeprecatedFoo as GlFoo } from '@gitlab/ui';

    This keeps the diff small and easy to review, since templates don't need to change, and no visual or behavioral changes need to be verified. It also reduces the amount of work that needs to be done in later steps.

  3. Duplicate the existing GlFoo implementation, naming one copy GlDeprecatedFoo, and export it as GlDeprecatedFoo. This copy should receive no further changes.

  4. Implement the breaking changes on the copy exported as GlFoo, and release this in a new major version.

  5. Open integration MRs with projects that consume GitLab UI (e.g., GitLab) that bump @gitlab/ui to the new major version, and fix any additional new uses of GlFoo to import GlDeprecatedFoo instead. The amount of these should be significantly reduced thanks to step 2.

  6. Open an epic to iteratively upgrade each use of GlDeprecatedFoo to the new GlFoo. There is a script that helps automate some of this.

  7. Once all uses have been upgraded in the consuming projects, completely remove GlDeprecatedFoo from GitLab UI and release it as another major version, since it's another breaking change.

  8. A final set of integration MRs can now be opened which bump @gitlab/ui to the new major version, and any new uses of GlDeprecatedFoo (but hopefully there are none) can be upgraded to GlFoo.

Note that if GlFoo were only used once or twice in consuming projects, some of the steps in this process would be unnecessary overhead; it might be easier to immediately upgrade those uses to the new implementation in the same integration MR that bumps @gitlab/ui to the new major version.

Remember to follow our commit conventions to ensure the major version number of GitLab UI is incremented with any breaking changes.