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
[edit]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: T0123456
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
[edit]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.
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
[edit]- 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