Large projects in Gerrit rely on the Depends-On feature.

We need to investigate and document how to use this in GitLab.

We'll use this task as a parent task for investigations and a placeholder for general discussion.

What is Depends-On

Depends-On is a feature of zuul-ci project gating that enables cross-repo dependencies.

This feature enables large code bases to be tested together without belonging to a single large repository (monorepo).

Developers may add a Depends-On git trailer to the commit message of a patchset to indicate it depends on another patchset in a different git repo on Gerrit. The trailer, currently, references the dependency's Change-Id—an automatically generated hash for a patch. The Change-Id of of the patchset of the dependency. It's integrated with our Gerrit via a plugin.

Depends-On use-cases

These are the use-cases we should address for Depends-On:

1. Block a dependent patchset from merging before its dependencies.
   • Example: mediawiki/extension/Foo "patchB" Depends-On → mediawiki/core "patchA"
     • "patchA" must be merged before "patchB"
2. Tests run with their dependencies applied.
   • This is not for for linting or static analysis, but for integration tests.
   • Example: mediawiki/extension/Foo "patchB" Depends-On → mediawiki/core "patchA"
     • check out mediawiki/core
     • Apply "patchA"
     • check out mediawiki/extension/Foo
     • Apply "patchB"
     • Run the integration tests
     • Report test results to "patchB"
   • There may also be transitive dependencies
3. Cross-project merge queue
   • After +2, before merge, we queue changes for gating tests.
   • During gating, each patchset in the queue depends on the patch in front of it.
   • This ensures that patchsets work together
     • GitHub and GitLab implement this feature only within a single project (GitHub merge queues and GitLab merge trains)
     • To ensure continuous delivery of MediaWiki we need a cross-project merge queue.
   • Example: mediawiki/extension/Bar "patchD" get +2'd; mediawiki/core "patchC" is already gating
     • "patchD" → Depends-On → "patchC" (see point #2 above)
     • If PatchC has changes which cause integration tests to fail for PatchD, PatchD will not merge and PatchD will be notified
     • If PatchC fails, PatchD is automatically requeued and tested by itself; if it passes, it merges.