| :linkattrs: | |
| = Gerrit Code Review - Submitting Changes Across Repositories by using Topics | |
| == Goal | |
| This document describes how to propose and submit code changes across multiple | |
| Git repositories together in Gerrit. | |
| == When to Use | |
| Oftentimes, especially for larger code bases, code is split across multiple | |
| repositories. The Android operating system’s code base, for example, consists of | |
| https://android.googlesource.com/[hundreds] of separate repositories. When | |
| making a change, you might make code changes that span multiple repositories. | |
| For example, one repository could define an API which is used in another | |
| repository. Submitting these changes across these repositories separately could | |
| cause the build to break for other developers. | |
| Gerrit provides a mechanism called link:intro-user.html#topics[Topics] to submit | |
| changes together to prevent this problem. | |
| |=== | |
| |NOTE: Usage of topics to submit multiple changes together requires your | |
| Gerrit host having | |
| link:config-gerrit.html#change.submitWholeTopic[config.submitWholeTopic] set to | |
| true. Ask your Gerrit administrator if you're not sure if this is enabled for | |
| your Gerrit instance. | |
| |=== | |
| == What is a Topic? | |
| * A topic is a string that can be associated with a change. | |
| * Multiple changes can use that topic to be submitted at the same time (assuming | |
| approvals, etc.). | |
| * Submitting a change with a topic causes all of the changes in the topic *to be | |
| submitted together* | |
| ** Topics that span only a single repository are guaranteed to be submitted | |
| together | |
| ** Topics that span multiple repositories simply triggers submission of all | |
| changes. No other guarantees are given. Submission of all changes could | |
| fail, so you could get a partial topic submission. This is very rare but | |
| can happen in some of the following situations: | |
| *** Storage layer failures. This is unlikely in single-master installation and | |
| more likely with multi-master setups. | |
| *** Race conditions. Concurrent submits to the same repository or concurrent | |
| updates of the pending changes. | |
| Here are a few intricacies you should be aware of: | |
| 1. Topics can only be used for changes within a single Gerrit instance. There is | |
| no builtin support for synchronizing with other Gerrit or Git hosting sites. | |
| 2. A topic can be any string, and they are not namespaced in a Gerrit instance; | |
| there is a chance for collisions and inadvertently grouping changes together | |
| that weren’t meant to be grouped. This could even happen with changes you can’t | |
| see, leading to more confusion e.g. (change not submittable, but you can't see | |
| why it's not submittable.). We suggest prefixing topic strings with the author’s | |
| username e.g. “username-” to help avoid this. | |
| You can view the assigned topic from the change screen in Gerrit: | |
| image::images/cross-repository-changes-topic.png[width=600] | |
| === Topic submission behavior | |
| * Submitting a topic will submit any dependent changes as well. For example, | |
| an unsubmitted parent change will also be submitted, even if it isn’t in the | |
| original topic. | |
| * A change with a topic is submittable when *all changes* in the topic are | |
| submittable and *all of the changes’ dependent changes* (and their topics!) | |
| are also submittable. | |
| * Gerrit calls the totality of these changes "Submitted Together", and they can | |
| be found with the | |
| link:rest-api-changes.html#submitted-together[Submitted Together endpoint] or | |
| on the change screen. | |
| image::images/cross-repository-changes-submitted-together.png[width=600] | |
| * A submission creates a unique submission ID | |
| (link:rest-api-changes.html#change-info[`submission_id`]), which can be | |
| used in Gerrit's search bar to find all the submitted changes for the | |
| submission. This ID is relevant when <<reverting,reverting a submission>>. | |
| To better underestand this behavior, consider this following example. | |
| [[example_submission]] | |
| === Example Submission | |
| image::images/cross-repository-changes-example.png[width=600] | |
| * Two repositories: A and B | |
| * Two changes in A: A1 and A2, where A2 is the child change. | |
| * Two changes in B: B1 and B2, where B2 is the child change. | |
| * Topic X contains change A1 and B1 | |
| * Topic Y contains change A2 and B2 | |
| Submission of A2 will submit all four of these changes because submission of A2 | |
| submits all of topic Y as well as all dependent changes and their topics i.e. A1 | |
| and topic X. | |
| Because of this, any submission is blocked until all four of these changes are | |
| submittable. | |
| |=== | |
| | Important point: B1 can unexpectedly block the submission of A2! | |
| This kind of situation is hard to immediately grok: B1 isn't in the topic you're | |
| trying to submit, and it isn't a depnedent change of A2. If your topic isn’t | |
| submittable and you can’t figure out why, this might be a reason. | |
| |=== | |
| == Submitting Changes Using Topics | |
| === 1. *Associate the changes to a topic* | |
| The first step is to associate all the changes you want to be submitted together | |
| with the same topic. There are multiple ways to associate changes with a topic. | |
| ==== From the command line | |
| You can set the topic name when uploading to Gerrit | |
| ---- | |
| $ git push origin HEAD:refs/heads/master -o topic=[YOUR_TOPIC_NAME] | |
| ---- | |
| *OR* | |
| ---- | |
| $ git push origin HEAD:refs/for/master%topic=[YOUR_TOPIC_NAME] | |
| ---- | |
| If you’re using https://source.android.com/setup/develop[repo] to upload a | |
| change to Android Gerrit, you can associate a topic via: | |
| ---- | |
| $ repo upload -o topic=[YOUR_TOPIC_NAME] | |
| ---- | |
| If you’re using | |
| https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html[depot_tools] | |
| to upload a change to Chromium Gerrit, you can associate a topic via: | |
| ---- | |
| $ git cl upload --topic=[YOUR_TOPIC_NAME] | |
| ---- | |
| ==== From the UI | |
| If the change has already been created, you can add a topic from the change page | |
| by clicking ADD TOPIC, found on the left side of the top of the Change screen. | |
| image::images/cross-repository-changes-add-topic.png[width=600] | |
| === 2. *Go through the normal code review process* | |
| Each change still goes through the normal code review process where reviewers | |
| vote on each change individually. The changes won’t be able to be submitted | |
| until *all* changes in the topic are submittable. | |
| The requirements for submittability vary based on rules set by your repository | |
| administrators; often this includes being approved by all requisite parties, | |
| passing presubmit testing, and being able to merge cleanly (without conflicts) | |
| into the target branch. | |
| === 3. *Submit the change* | |
| When all changes in the topic are submittable, you’ll see *SUBMIT WHOLE TOPIC* | |
| at the top of the _Change screen_. Clicking it will submit all the changes in | |
| "Submitted Together." | |
| image::images/cross-repository-changes-submit-topic.png[width=600] | |
| [[reverting]] | |
| == Reverting a Submission | |
| After a topic is submitted, you can revert all or one of the changes by clicking | |
| the *REVERT* button on any change. | |
| image::images/cross-repository-changes-revert-topic.png[width=600] | |
| This will give you the option to either revert just the change in question or | |
| the entire topic: | |
| image::images/cross-repository-changes-revert-topic-options.png[width=600] | |
| Reverting the entire submission creates revert commits for each change and | |
| automatically associates them together under the same topic. To submit | |
| these changes, go through the normal review process. | |
| When submitting a topic, dependent changes and their topics are submitted as | |
| well. The RevertSubmission creates reverts for all the changes that were | |
| submitted at that time. When reverting the submission described in | |
| <<example_submission,Example Submission>>, all 4 of those changes will get | |
| reverted. | |
| |=== | |
| | NOTE: We say “reverting a submission” instead of “reverting a submitted | |
| topic” because submissions are defined by submission id, not by the topic | |
| string. So even though topics names could be reused, this doesn't effect | |
| reverting. For example: | |
| 1. Submission #1 uses topic A | |
| 2. Later, Submission #2 uses topic A again | |
| Reverting submission #2 only reverts the changes in that submission, not all | |
| changes included in topic A. | |
| |=== | |
| == Cherry-Picking a Topic | |
| You may want to cherry-pick the changes (i.e. copy the changes) of a topic to | |
| another branch, perhaps because you have multiple branches that all need to be | |
| updated with the same change (e.g. you're porting a security fix across | |
| branches). Gerrit provides a mechanism to create these changes. | |
| From the overflow menu (3 dot icon) in the top right of the Change Screen, | |
| select “Cherry pick.” In the screenshot below, we’re showing this on a | |
| submitted change, but this option is available if the change is pending as | |
| well. | |
| image::images/cross-repository-changes-cp-menu.png[width=600] | |
| Afterwards, you’ll be presented with a modal where you can “Cherry Pick entire | |
| topic.” | |
| image::images/cross-repository-changes-cp-modal.png[width=600] | |
| Enter the branch name that you want to target for these repositories. The | |
| branch must already exist on all of the repositories. After clicking | |
| “CHERRY PICK,” Gerrit will create new changes all targeting the entered | |
| branch in their respective repositories, and these new changes will all be | |
| associated with a new, uniquely-generated topic name. | |
| To submit the cherry-picked changes, go through the normal submission | |
| process. | |
| |=== | |
| | NOTE: You cannot cherry pick two or more changes that all target the same | |
| repository from the Gerrit UI at this time; you’ll get an error message saying | |
| “changes cannot be of the same repository.” To accomplish this, you’d | |
| need to do the cherry-pick locally. | |
| |=== | |
| == Searching for Topics | |
| In the Gerrit search bar, you can search for changes attached to a specific | |
| topic using the `topic` operator e.g. `topic:MY_TOPIC_NAME`. The `intopic` | |
| operator works similary but supports free-text and regular expression search. | |
| You can also search for a submission using the `submissionid` operator. Topic | |
| submission IDs are "<id>-<topic>" where id is the change number of the change | |
| that triggered the submission (though this could change in the future). As a | |
| full example, if the topic name is my-topic and change 12345 was the one that | |
| triggered submission, you could find it with `submissionid:12345-my-topic`. | |