Contents
Deprecation
THE CONTENT ON THIS PAGE IS NO LONGER VALID.
We have tried to use Gerrit, but we decided not to continue with it, so the content of this page is kept as historical reference only.
Introduction
This page is a guide to using GDB's Gerrit instance. There is a lot of resources online on how to use Gerrit, but this page explains how we use it in particular. As described in more details below, we use Gerrit to review patches, but pushing/merging/landing the patch (however you want to call it) is still done as usual, by pushing to Sourceware.
The goal of Gerrit is to be able to upload patches (in the form of git commits) and get others to review them. Some advantages of Gerrit over sending patches by email are:
- With emails, it can sometimes be difficult to apply patches on a local work tree. Patches can be malformed. They can not apply anymore because the master branch has progress, so we need to guess which commit it is based on. Gerrit changes (patches) are uploaded in the form of git commits, it is trivial to check them out locally, they can't fail to apply.
- With emails, it is possible for patches to get lost. In an individual's email inbox, it is not easy to see at a glance which patches have been merged, and which ones still need a review. In Gerrit, changes are clearly identified as open or closed.
- It makes it easy to compare two versions of a same patch.
One time setup
These steps need to be done once to get you started. Obviously, you'll need to repeat the Add an SSH key step if you want to use a new SSH key, or the Set up your local git repository if you clone again the Sourceware repository from scratch in the future.
Create an account
Click Sign in in the top-right corner,
Click Register and fill the form to create a new account.
Once you are registered, the system should send you back to Gerrit, and you should be logged in (you should now see your name in the top-right corner).
Add an SSH key
When interacting with Gerrit with git (for example, to send a patch for review), you identify yourself with your username and an SSH key. To add a key to your account:
- Go to your User Settings page, by clicking on the gear icon in the top-right corner,
Go to the SSH keys section,
Paste your public SSH key in the New SSH key box, then click ADD NEW SSH KEY.
The format of the public SSH key is the usual OpenSSH format:
ssh-rsa AAAAB3NzaC1y...a long string...GUTyp6W3GVxvs073T357SHCwnc= comment
The comment part just helps differentiates your keys if you have multiple, it is not actually part of the key. You can put whatever you want as the comment, or it can be omitted.
Set up your local git repository
To push a patch for review on Gerrit, you will push your git commit to Gerrit's special git repository. To do so, you will need to have Gerrit as a git remote. Your commit will also need to have a Change-Id line, which helps identify different versions of the same patch. A commit-msg hook provided by Gerrit can automatically insert a Change-Id line every time you edit a commit message (if it isn't there already).
If we were setting up a local repository from scratch, we could just go to Gerrit's binutils-gdb project page, copy the Clone with commit-msg hook command, run it, and we'd be done. However, these instructions assume that you already have a repository with Sourceware as the origin, so we do things a bit more by hand.
The following command adds the remote with the name gerrit, which is used in further instructions on this page.
git remote add gerrit ssh://<YOUR-USERNAME>@gnutoolchain-gerrit.osci.io:29418/binutils-gdb
To install the commit-msg hook, use:
scp -p -P 29418 <YOUR-USERNAME>@gnutoolchain-gerrit.osci.io:hooks/commit-msg "binutils-gdb/.git/hooks/"
You can find both of these URLs (including your username) in the Clone with commit-msg hook command, on Gerrit's binutils-gdb project page.
If you get some permission denied error, it's probably because your public SSH key is not set up properly, or the ssh-based commands above don't find your private SSH key.
You may want to set up the new remote so that git fetch --all does not fetch from Gerrit. You can do this using:
git config remote.gerrit.skipDefaultUpdate true
Patch review workflow
Uploading and updating a patch
Gerrit acts as a git repository to which you can push and fetch commits (or "refs"). Uploading a patch on Gerrit consists of pushing a git commit to a special refs/for/BRANCH branch, where BRANCH is the name of the branch the commit is based.
For example, let's say you make one cool commit based on the master branch that you would like to upload to gerrit and get reviewed:
commit f5203b75aa5a3b207d262f829013a1f27cd62d0c (HEAD -> master)
Author: Simon Marchi <simon.marchi@polymtl.ca>
Date: Sun Oct 13 18:15:12 2019 -0400
My very cool commit
Change-Id: Iadcbd329fa5a7c14c64ecdd1dff60c5c45a1bee3
commit d039f01465b37026e538b06ff792aadc4b19bf24 (origin/master, origin/HEAD)
Author: Tom de Vries <tdevries@suse.de>
Date: Sun Oct 13 15:09:09 2019 +0200
Mention PR c++/20020 in ChangeLog entry
[ Port of gdb-8.3-branch commit 59047affb0a "Update ChangeLog entry of commit
98c90f8028 and mention PR c++/20020". ]
...Commit d039f014 is the latest commit on the upstream master branch, while the f5203b75 is the commit to upload. The following command could be used to push the commit to Gerrit:
$ git push gerrit HEAD:refs/for/master
HEAD refers to the currently checked out commit, but we could have used f5203b75 or master instead, since they refer to the same commit. If it worked, you should read something like:
remote: SUCCESS remote: remote: https://gnutoolchain-gerrit.osci.io/r/c/binutils-gdb/+/27 My very cool commit [NEW]
If you made multiple commits on top of the target branch, Gerrit will open one change per commit.
To upload a new version of the patch (for example, to address review comments) simply edit (amend) the commit and push it again with the same command. Gerrit will recognize that the Change-Id corresponds to an existing change and will file it as version 2 of that change.
To rebase a patch on the current version of master (or whatever the target branch for a change is), you can use the Rebase button in the Gerrit interface, if the rebase is trivial. Otherwise, you can do the rebase locally and push the patch again. In both cases, this will create a new version of the patch.
If you are addressing review comments, make sure to mark them as Resolved to let the reviewer know that you have addressed or acknowledged it.
Reviewing a patch
Gerrit has a tendency to log you out, so before trying any of the below, make sure you are logged in (Sign In link on the topright).
This is how the page of a patch should look once you are logged in:
To checkout out the code locally, click on the three dots on the top right of the page and choose Download patch. The popup offers you different ways of integrating the git commit to your local repository. You will typically want to use the Checkout method, which uses git checkout to check out the commit exactly as the author has pushed it. If the author has pushed multiple consecutive commits (aka a patch series), you can use this on the last commit to check out the entire series.
You can see the code changes below on the page of the patch. That's where you can leave comments, including on the commit message.
To add review comments from the Gerrit interface, click on line number where you want to add the comment (see next section for more details on different ways to leave comments). Write your comment, then click Save, which will save your comment as a draft. You can add multiple such comments, edit or delete them, while they are drafts. To publish them all at once, go back to the page of the patch and click Reply (the big blue button on the screenshot above). There, you can add a general comment and give a code review score, in addition to publishing your comments on the code.
The code review score have the following meaning:
+2: Accessible to global, arch and subsystem maintainers. The patch is approved, you can go ahead and merge it.
+1: Accessible to all, the patch looks good to me, but someone else must approve.
-1: I would prefer the patch not merged as-is. This is what should be used if you have comments requesting changes to the patch.
If you review a patch (whether you are a maintainer or not) and request some changes, please don't hesitate to set the code review score to -1. It helps to notice that somebody has looked at the patch and that the ball is back in the court of the author.
A nice feature of Gerrit is that it allows you to compare two versions of the same change. So if you left review comments that were allegedly addressed, you can compare the version on which you left the comments with the latest version to see which modifications have been made to the patch.
Writing comments
There are a few ways to leave comments.
To target a single line, click the line number on the left:
To target a whole file (e.g. to say that it should or should not be renamed), click the File button at the top:
To target a range of code, select the range of code and press c. The range can be a portion of a line (e.g. target a single word) or span multiple lines.
Whenever you comment on Gerrit, an email notification is sent to the gdb-patches mailing list. This email includes the lines of code your comment targetted, plus 5 lines of context before/after. To make sure email notifications include enough context to make following the comments in the mailing list reasonable, it is recommended to default to targetting a range of code, covering all the context relevant to your comment.
If you reply to a comment, please quote the comment you are replying to in your own comment (like you would quote when replying to an email). This will give some context to people following on the mailing list.
If you want to write snippets of code in your comment, begin those lines with a space, like so:
I think you should format it like this:
if (foo)
{
...
}
Pushing a patch
Since we share our repository with the fine people from binutils, who do not use our Gerrit instance (for the moment!), we use Gerrit to review patches, but we don't use its Submit feature, which would allow to merge the patch in the target branch with the click of a button. Doing so would make the repository inside Gerrit and repository on Sourceware diverge.
Therefore, patches are still pushed to the Sourceware repository as before. The Gerrit repository is automatically synchronized with the Sourceware repository. When Gerrit notices that a patch has been merged (it matches the Change-Id), it automatically closes the corresponding change and marks it as Merged.
Keyboard shortcuts
There are some pretty useful keyboard shortcuts to help navigate faster in the interface. Press ? in Gerrit to see a pop-up help panel with the keyboard shortcuts.
git-review
The git-review tool is a wrapper that simplifies some of the operations described above, so it's probably worth checking out.
Queries and command-line interface
Gerrit has a pretty featureful query language. For example here's how to list all currently open reviews for the binutils-gdb project: https://gnutoolchain-gerrit.osci.io/r/q/project:binutils-gdb+is:open
- You can interact with the Gerrit server from the command line through SSH, if you want to do your own scripting. For example:
ssh <YOUR-USERNAME>@gnutoolchain-gerrit.osci.io -p 29418 gerrit --help
ssh <YOUR-USERNAME>@gnutoolchain-gerrit.osci.io -p 29418 gerrit query --format JSON is:open project:binutils-gdb