Working across different petals

Hard and Soft Transitions

Because it is not possible to atomically commit a change to multiple Git repositories at once, coordinating changes that affect multiple petals - for example, an API or ABI change in the Fuchsia tree that affects callers in Topaz or Experiences - requires either a soft or hard transition.

Terminology:

  • D - A project used in the Fuchsia tree.
  • P - Another project used in the Fuchsia tree with a direct dependency on D. For example, D might be Fuchsia, and P might be Topaz or Experiences.
  • integration - The internal integration repository.

Soft transitions (preferred)

The preferred way to make changes that span multiple projects is to use a soft transition. In a soft transition, you make a change to D in such a way that the interface supports both old and new clients. For example, if you are replacing a function, you might add the new version and turn the old function into a wrapper for the new function.

Use the following steps to land a soft transition:

  1. Land the change in D that introduces the new interface without breaking the old interface used by P.
  2. Wait for the new revision of D to roll into the integration repository.
  3. Migrate P to use the new interface.
  4. Wait for the new revision of P to roll into the integration repository.
  5. Land a cleanup change in D to remove the old interface.

Hard transitions

For some changes, creating a soft transition can be difficult or impossible. For those changes, you can make a hard transition. In a hard transition, you make a breaking change to D and update P manually.

Note that to prevent accidental clobbering of the manifest contents, Gerrit is configured to not automatically rebase changes that edit a manifest file. You must manually rebase before merging so that your submit is a pure fast-forward.

Making a hard transition is more stressful than making a soft transition because your change will be preventing other changes in 'D' from becoming available in dependent projects between steps 1 and 2.

Only Google developers can make hard transitions. See internal documentation for instructions.