blob: 20698596569de80b9a7038f53e651dbdf0c36215 [file] [log] [blame] [view]
# 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`.
1. Wait for the new revision of `D` to roll into the integration repository.
1. Migrate `P` to use the new interface.
1. Wait for the new revision of `P` to roll into the integration repository.
1. 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.
[getting-source]: /docs/development/source_code/README.md "Getting source"