Gerrit/Cross-repo dependencies

Cross-repo dependencies are commits to other repositories which a commit requires for functioning correctly. For example, you want to add new functionality to an extension, but there is no hook for it, so you submit a core patch adding a new hook, and a patch to the extension adding a handler for that hook. Declaring the core patch as a dependency of the extension patch ensures that the extension patch is not tested and not merged without the core patch.

How to declare cross-repo dependencies

Cross-repo dependencies can be declared with a Depends-On tag in the commit message, a syntax similar to that of connecting patches to Phabricator tasks: in the commit message, you write something like

Subscribe to Foo hook

The extension now uses the Foo hook to make foo.

Bug: T123456
Depends-On: I123456abc...
Change-Id: I456790def...

where I123456abc... is the 40-character Gerrit ID of the other commit (which is in the Change-Id line of the commit message of that commit).

This has two effects:

• Zuul (the gatekeeper of the MediaWiki continuous integration system) will refuse to merge the patch until all dependencies are merged.
• whenever the CI system builds a test environment, all dependencies are cherry-picked on top of the master branches of their respective repositories; thus, even if your extensions tests depend on the new core functionality, the tests will work correctly.

Both of these also work recursively, if the dependencies themselves have dependencies.

Possible problems

If one of the dependencies cannot be merged (typically, because it has a merge conflict and needs rebase) the CI system will refuse to run tests, and jenkins-bot will report an error like This change or one of its cross-repo dependencies was unable to be automatically merged with the current state of its repository. instead. In some rare cases, this very same message could indicate a corruption in the Git repository, see T134062.

Tracked in Phabricator
Task T210685

Depends-On may not work properly if more than one change in Gerrit has the same Change-Id, such as when a dependency is cherry-picked onto a release branch. In such cases, jenkins-bot may or may not report an error like This change depends on a change that failed to merge. As a workaround, remove the existing Change-Id whenever you cherry-pick a cross-repo dependency onto another branch. If you forgot to do this and already published the cherry-pick, you will not be able to use Depends-On unless you reupload the cross-repo dependencies under different Change-Ids (abandoning all but one of them will not fix the problem).

More information

• Documentation (note that this page describes a different way of declaring cross-repo dependencies, which is not supported by the version of Zuul used by Wikimedia)
• Zuul documentation (see note above)
• Email announcement