Skip to content

Eliminating the `@gitlab/ui` Migration Path Bottleneck

Problem

The current dependency setup between @gitlab/duo-ui, @gitlab/ui, and host systems creates a migration bottleneck.

Initial State (Example Versions)

Host System Dependencies:

  • @gitlab/ui: 100.0.0
  • @gitlab/duo-ui: 1.0.0 (with a peer dependency on @gitlab/ui ^100)

Scenario

  1. A new major version of @gitlab/ui (101.0.0) is released.
  2. The host system cannot upgrade to @gitlab/ui 101.0.0 because @gitlab/duo-ui 1.0.0 enforces a peer dependency on @gitlab/ui ^100
  3. To resolve this, a new version of @gitlab/duo-ui (2.0.0) must be released with an updated peer dependency @gitlab/ui ^101
  4. Only after this release can the host system migrate to @gitlab/ui 101.0.0 and @gitlab/duo-ui 2.0.0

Impact

This dependency relationship makes @gitlab/duo-ui a bottleneck for all systems that rely on both @gitlab/ui and @gitlab/duo-ui Every breaking change in @gitlab/ui requires a coordinated release of @gitlab/duo-ui, delaying adoption across host systems.

Solution

Step 1: Relax Peer Dependency Restrictions

Since @gitlab/duo-ui only uses a small subset of the components provided by @gitlab/ui, the likelihood of being affected by breaking changes in @gitlab/ui is low—but not zero.

We could define a more permissive peer dependency in @gitlab/duo-ui, such as:

"peerDependencies": {
  "@gitlab/ui": ">100"
}

This approach unblocks the release path for @gitlab/ui but introduces a risk of breaking @gitlab/duo-ui in production when incompatibilities arise.

Step 2: CI/CD Integration to Validate Compatibility

To ensure compatibility without blocking releases, we need to enhance the host system’s CI/CD pipeline to trigger a @gitlab/duo-ui pipeline during every build.

Implementation

  • Integrate the @gitlab/duo-ui pipeline into the host system’s build process.
  • On every host system build, test @gitlab/duo-ui against the latest @gitlab/ui changes.
  • This allows breaking changes in @gitlab/ui to proceed without delay while immediately catching any compatibility issues with @gitlab/duo-ui at the CI stage.

Having this implemented will:

  1. Allow @gitlab/ui to release updates, including breaking changes, without being delayed by dependency constraints in @gitlab/duo-ui.
  2. Ensure Stability: Catch any compatibility issues between @gitlab/duo-ui and the latest @gitlab/ui versions early in the CI/CD pipeline, preventing potential disruptions in production.
  3. reduce dependency management overhead for host systems.