Dependent Changes in Gerrit

The Fuchsia project contains many separate repositories. To make cross-repository changes easier, Fuchsia's Gerrit host supports declaring dependencies between changes in different repositories. Dependencies are respected during presubmit testing and change submission.

Usage

To declare a CL's dependency on another CL, include a Depends-on footer in the commit message. A CL can have multiple dependencies, spanning different repositories and Gerrit hosts.

Format:

[foo] Do something

Depends-on: Idc82d1483b4be8480aaa87bb48af8d03cfa45858
Change-Id: Ibbf13ab7de7e4444a2dc1f52f3cad97e76c7721d

Specification

  • The value of each Depends-on footer must be a Gerrit change ID. Only change IDs are accepted; integer change numbers are not.
  • If the dependency is on a different Gerrit host from the current CL, the host must be specified as a prefix (e.g., turquoise-internal:I9916ccaa4b95b6e9babdee33014fa6bd3d478f2e).
  • Depends-on footers must be in the last paragraph of the commit message, with no blank lines between Depends-on and the Change-Id footer.
  • The Depends-on footer is case-sensitive and other spellings are not accepted.
  • If a Depends-on footer references a non-existent CL, a comment will be added to the CL.

Behavior and Interaction with Infrastructure

  • Submission blocking: A CL that has a Depends-on footer will not be submittable until all of its dependencies are submitted, at which point the "CL Deps Checker" robot will vote Dependencies-Satisfied +1 which will make the CL submittable.
  • Presubmit Testing: For easier testing, if CL A depends on CL B, then CL B will also be patched into the checkout in presubmit testing of CL A. The Depends-on footer is also handled recursively, so that transitive dependencies are respected.
  • Auto-submit: This system will work best if the CL uploader uses Fuchsia's auto-submit feature. If auto-submit is enabled on a chain of CLs with Depends-on footers, they will land in the correct order with no manual intervention necessary.

Circular Dependencies (Atomic Changes)

To use circular dependencies:

  1. Upload the two CLs with Depends-on footers referencing each other.
  2. Get the necessary approvals on both CLs.
  3. Set Fuchsia-Auto-Submit +1 on both CLs once you're ready to land them.

The CL Deps Checker robot will take care of the rest, doing a presubmit dry run on both CLs and approving them both simultaneously if the dry runs pass.

Then auto-submit will submit the CLs, and the roller into integration.git will roll the CLs in a single commit.