Created by on 2010 Sep 14 1
1. Starting a Patch To create a patch, and get it through the review process and into a main branch of a project, you can follow the following steps: Clone the project if you haven't already. Checkout the branch into which you want the change to go. Pull from origin to make sure you have the latest commits for the branch on your machine. Create a topic branch from the target branch. If you have a JIRA, you can name the topic branch after it. E.g.: git clone gerrit:gerrit/training localdir # if you haven't cloned yet cd localdir git checkout master git pull origin # if you have cloned before, and just need to pull in the latest changes git checkout -b TWD-220 You now have a local branch called TWD-001, which is where you will be developing the patch. The local branch points at the same commit as master at this stage. Do your work, and commit often. If you want to make small commits at this stage, you can, but then you'll need to rebase and squash them later. If you want to save the work on the server, you can push the local branch to your sandbox space. git push origin HEAD:sandbox/carl.heymann/TWD-220 At this stage, your local branch has several commits. Initially, you will still be directly ahead of master in the commit tree, but as soon as another patch is Created by on 2010 Sep 14 2
submitted (merged) into master, you won't see master in your direct commit history anymore. Before submitting, you need to get the work squashed into a single commit, which can be reviewed. To do this, use an interactive squash. You can squash on the same branch, or make a new branch before squashing. To rebase the work on the master branch: git checkout -b TWD-220_review git rebase master --interactive At this point, you get an editor screen (e.g. vim), with some text. This is used as instructions for the rebase. It lists all commits that are only in the current branch (in chronological order, top to bottom), with instructions before each commit. Leaving each instruction as "pick" will simply replay the commits in order, creating new commits that follow from the master branch. You can change the instructions, as per the comments on the editor. Changing a "pick" to an "s" will squash that commit into the previous one (but you can merge the commit messages by hand), while "f" fill squash it and throw away the commit message. In this case, we can change it as follows: pick 4dc18bd TWD-220 Demo patch f 2de768c tmp commit # Rebase bb29643..2de768c onto bb29643 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # # If you remove a line here THAT COMMIT WILL BE LOST. # However, if you remove everything, the rebase will be aborted. When you save and exit, the rebase is carried out. If you have conflicts, you will need to fix these and then do a "git rebase --continue", or "git rebase --abort" to go back to the state before the rebase was started. Created by on 2010 Sep 14 3
The new state: The original TWD-220 branch still exists, and the server has a sandbox branch pointing at it as well. However, the new TWD-220_review branch has been created as a separate commit, rebased on master, with all the changes in the TWD-220 commits combined. This new commit is the one we will push for review. To push for review: git push origin TWD-220_review:refs/for/master 2. Performing a Review Now, the review shows up on gerrit, and you can add reviewers. Created by on 2010 Sep 14 4
Adding reviewers cause email to be sent to them, inviting them to review the change. Reviewers can view the changes by clicking on files, e.g. on "hello.txt" in this case. You can add comments by double-clicking on a line, then typing the comment. When you save it, it is still only visible to you (draft), but the server knows about it. It will only be published for all to see once you complete the review. Once you are done looking at files and typing comments, you can complete the review by clicking the "review" button on the change detail screen. Then, you must select radio buttons, to show if you can confirm the following: o o Verified: the change compiles and runs unit testes (verified +1) or not (-1), or if you have no opinion (0). Code Review: the change looks good, and may be submitted to the intended branch (+2) the change looks good, but someone else must decide if it can be submitted (+1) no opinion (0) Created by on 2010 Sep 14 5
the change looks bad, and you'd prefer that it is not submitted, but you won't veto the submit completely (-1) the change may not be submitted (-2) If a change has either a -1 verified or a -2 code review state, it cannot be submitted to the target branch. Furthermore, it requires at least a +1 verified and a +2 code review from any reviewer before it can be submitted. Remember, any developer can set -1..+1 verified and -2..+2 code review states, so all developers have full approval and veto rights on all projects. However, only someone from the relevant leads group can submit the patch to the target branch. NB: don't set Code Review = +2 on your own patches. We cannot enforce this (yet) but we can query for it using the reviewdb database. Once the review is completed, the other reviewers, and the originator get emails. 3. Creating a Second Patch Set To create a second patch set, e.g. after a change was rejected in the review process, you need to get the branch with the commit that was pushed initially. If you still have that branch, you can check it out, e.g. git checkout TWD-220_review 3.1. Getting review code in a local branch If you don't have the branch, then you can create it anywhere. Look for the change ref in the patch detail page. You can create the branch as follows: git fetch origin refs/changes/40/40/1 && git checkout -b TWD- 220_review FETCH_HEAD What happens is the following: You fetch the specific point in the commit tree from gerrit. That point is stored temporarily in the local git repo under the special ref name "FETCH_HEAD" (git does this whenever you fetch on a specific commit). You then create a local branch named "TWD-220_review", with the branch tip pointing at the same commit as "FETCH_HEAD". From this point on, the branch is a regular local branch, and you can continue. Created by on 2010 Sep 14 6
3.2. Changing the Change To prepare the second patch set, you simply go to the topic branch (which has the originally pushed commit for the change) make the changes, then commit with the --amend flag. git commit --amend -C HEAD Amending the commit simply adds the changes you've made to the commit, so there is still only a single commit. The "-C HEAD" tells git to use the same commit message as the HEAD commit, i.e. the commit we're amending, so the commit message is unchanged. If you want to change the commit message, just leave out the -C option and you will get an editor to edit the message. NB: Make sure the change-id in the commit stays the same, so gerrit can correlate the change. If it's not there, you don't have the commit hook set up. Paste the change ID at the end of the commit message, leaving a blank line before it. You can get the change ID line by copying from the change detail screen. To tell gerrit about the patch: git push origin HEAD:refs/for/master Exactly as before. Gerrit creates a patch set, which must be reviewed. At this stage, the repository in our example looks like this: You can see that another change, "CHG-2" has been merged into the master branch since you started working on TWD-220. Gerrit shows the patch as patch set 2 on the same change: Created by on 2010 Sep 14 7
If you look at the file, you can see how it changed from e.g. patch set 1 If the patch is verified and reviewed OK, then the project lead can submit the patch. If there is a merge conflict, gerrit will tell you: "Your change could not be merged due to a path conflict. Please merge (or rebase) the change locally and upload the resolution for review." To fix the conflict, you must rebase the patch branch on master, then submit again. # get the latest master commits from gerrit git checkout master git pull origin # go the review branch and rebase git checkout TWD-220_review git rebase master # solve merge conflicts, then: git rebase --continue # upload the rebased commit git push origin HEAD:refs/for/master Created by on 2010 Sep 14 8
Note that the rebase on master will only work properly if you haven't committed directly to master before. If you have, you will be rebasing on your own version of master. To get your master branch back to tracking origin/master: # First make sure that your working directory is clean.. # Save your master branch under a different branch name git branch savemaster master # Reset your master branch back to the gerrit master branch git checkout master git reset --hard origin/master After this, you can do the rebase as described before. After pushing this (3rd) patch set to gerrit, it must be reviewed and submitted again via the web interface. If this has succeeded, you can see the commit in the master branch. git checkout master git pull origin The tree now looks like this: You can clean up the TWD-220 branch by deleting it, and also the sandbox branch on the server: git branch -D TWD-220 git push origin :sandbox/carl.heymann/twd-220 Note that pushing nothing to a remote branch deletes it on the gerrit server. You can also delete the sandbox branch via the gui (Admin->Projects->select project->branches) 3.2.1. Sample of a Successful Review Sample review Created by on 2010 Sep 14 9
3.2.2. The effect of parallel work, on repo history Doing a lot of independent, parallel work on a repository has the effect of creating merge commits, i.e. commits with multiple parents, which pull different branches together. An example of this is shown here: As you can see, the TWD-219, TWD-225 and TWD-221 work were all done independently, on different review branches, and merged by gerrit on successful submit. Created by on 2010 Sep 14 10