Gerrit Introduction

[toc align_right="yes" depth="2"]

Introduction to Gerrit

Note, if you are a first time Gerrit user, please take a look at the Setting-up-Gerrit page.

Overview

Main features

Gerrit is a web-based tool that is used for code review. Its main features are the side-by-side difference viewing and inline commenting which makes code reviews quick and simple task. It is used together with Git version control system. Gerrit allows authorized contributors to submit changes to Git repository, after reviews are done. Contributors can get their code reviewed with a little effort, and get their changes quickly through the system.

Gerrit usage

There are two purposes Gerrit usage. First, the contributor can upload changes to Gerrit, and second, approvers and peer reviewers can complete a review process with the web browser. Changes are uploaded with git push command. Any Git client can be used to access Gerrit. The review process includes the following steps:

• Review changes
• Publish comments
• Approve or abandon changes

Gerrit can manage multiple repositories (projects). Branches are fully supported by Gerrit, each repository can have any number of branches.

Gerrit stores changes, which are normal commits, as references in path refs/changes. When contributor pushes changes, a special reference in path refs/for/ is used. For example, when contributor uploads a commit to 'stable' branch the target ref will be refs/for/stable.

Git repositories that Gerrit operates on are accessed through Gerrit instead of git-daemon. Any other Git-related service can be used with Gerrit. However, it is recommended that all Git commands are run through Gerrit.

Terminology for Gerrit

Common terms used in Gerrit:

Term	Description
Change	A single commit and unit of a review. Changes are reviewed and submitted to Git repository.
Patch Set	A version of a change. After each time a change is modified, it will receive a new patch set.
Score	A value for approval category. Indicates if change is approved and can be submitted to the Git repository.
Approval Category	Name for a scope that is checked during review process. Qt is using categories Code Review and Sanity Review.
Submit	An action that allows Gerrit to merge a change to Git repository.
Abandon	Action that archives a change. An abandoned change can be restored later.
Project	Git repository.

Contribution creation and uploading

Git and Gerrit commands

All Gerrit commands are using SSH protocol and the host port is 29418. A user can access Gerrit's Git repositories with SSH or HTTP protocols. The user must have registered in Gerrit and a public SSH key before any command line commands can be used. Before proceeding user needs to have a SSH public key configured in Gerrit.

Creating a new contribution

All contributions will be uploaded with regular Git command, like before. Gerrit handles reviews in commit level. A single contribution can easily result in several reviewable changes in Gerrit. User, typically a contributor, prepares a contribution by following these steps:

1. Cloning from the repository
2. Setting up a commit message hook
3. Creating a topic branch
4. Doing changes
5. Updating repository
6. Pushing changes

See the step-by-step introductions below on how to complete a commit upload. Note that Gerrit SSH service is running in port 29418. There is no need to write this port number every time, just add the following lines to ~/.ssh/config file:

 Host codereview.qt.io
 User <username>
 Port 29418

Cloning from repository

The Qt Base Git repository can be cloned from Gerrit over SSH with the following commands:

 $ git clone ssh://codereview.qt.io/qt/qtbase.git
 Cloning into qtbase…
 remote: Counting objects: 33523, done
 remote: Finding sources: 100% (33523/33523)
 Receiving objects: 100% (33523/33523), 69.45 MiB | 901 KiB/s, done.
 remote: Total 33523 (delta 16501), reused 33523 (delta 16501)
 Resolving deltas: 100% (16501/16501), done.
 $

Note that the Qt Base repository only contains a limited part of Qt, including e.g. Qt Core, Qt GUI, Qt Network, but not Qt Webkit, Qt Script and others. If you want to clone everything, e.g. for building Qt Creator later, use

 $ git clone ssh://codereview.qt.io/qt/qt5.git
 $ cd qt5
 $ ./init-repository
 $ ./configure -developer-build # or your favourite setup

Setting up commit message hook

To add a Change-Id footer to your commit messages, download a message hook from Gerrit with the following command. The message hook should be downloaded for each submodule you will be editing. For qtbase, these commands work.

$ cd qtbase
$ scp codereview.qt.io:hooks/commit-msg .git/hooks

or (if you’re behind a firewall and want to use the https protocol):

$ cd qtbase
$ scp -P 443 codereview.qt.io:hooks/commit-msg .git/hooks

If you are cloning the qt5 supermodule and using the init-repository script, you will have the hooks installed automatically for you.

Creating a topic branch

Keep code organized in "topic branches.":http://git-scm.com/book/en/Git-Branching-Branching-Workflows This is what Git excels in. "next-big-thing" is used as an example topic branch below:

$ git checkout -b next-big-thing
Switched to a new branch 'next-big-thing'
$

h4. Doing changes

Use your favorite editor to complete a coding task.

$ edit src/foo.cc
$

h4. Updating repository

Call git add to all files that should be included in the commit that is created, and finally call git commit to create a new commit as follows:

$ git add src/foo.cc
$ git commit

At this point you will enter your commit message into the editor. The first line should be short and to the point, beginning with a verb like "Fix", "Optimize", "Add", etc. The second line must be blank. Following that should be a longer explanation of the change, yet still kept to the point.

A line in the form: "Task-number: QTBUG-01234" may be added to associate the commit with a bug report.

Save and quit the editor.

[next-big-thing c82710a] My Feature
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 src/foo.cc
$

After the first commit has been performed, if the commit-msg hook is set up properly, then an additional line in the form of "Change-Id: …" should have been added.

To revise the latest commit message use "git commit —amend".

Pushing changes

Changes are pushed to Gerrit with Git push. Note that special target ref is used. Gerrit reports how many changes were created and provides links to these changes.

 $ git push ssh://codereview.qt.io/qt/qtbase HEAD:refs/for/stable
 Counting objects: 6, done.
 Delta compression using up to 2 threads.
 Compressing objects: 100% (3/3), done.
 Writing objects: 100% (4/4), 407 bytes, done.
 Total 4 (delta 2), reused 0 (delta 0)
 remote: Resolving deltas: 0% (0/2)
 To ssh://<username>@codereview.qt.io:29418/qt/qtbase
  * [new branch] HEAD -> refs/for/stable
 $

When pushing to Gerrit, "a typical refspec":http://git-scm.com/book/en/Git-Internals-The-Refspec uses HEAD as source ref and special Gerrit ref for target branch. Target ref is in format

refs/for/<branch name>

. Pushes to this target ref causes Gerrit to create new changes for all commits pushed in this way. To group your changes push to a topic by using the format

refs/for/<branch name>/<topic name>

.

Note, that it is possible to use any other ref as source ref instead of HEAD when necessary. See Branch-Guidelines for branch information.

It is recommended that you use the git-gpush command from our "qtrepotools repositors":https://qt.gitorious.org/qt/qtrepotools (make sure to add the bin directory to your PATH for maximal convenience):

 $ git gpush
 [same output as above]

Requesting and receiving contribution feedback

Requesting contribution feedback

Contributor requests feedback by adding reviewers to the change. Typically this is done through web browser. Approver or another contributor who is doing peer-review can review any change without being added as a reviewer when having review access right to the project.

Access the change with web browser and use "Add Reviewer" button to add any other registered user to the review like in the picture below:

Alternatively, reviewers can be added already when uploading a contribution. When pushing a change, reviewers can be identified using receive-pack option. See example below and refer Gerrit user's guide for "more detailed instructions.":http://gerrit.googlecode.com/svn/documentation/2.1.6/user-upload.html#push_create Using cc option for receive-pack sends an e-mail notification to that user. Gerrit will avoid sending duplicate emails to the same user.

 $ git push —receive-pack=
  'git receive-pack —reviewer=approver@qt.io —cc qtcontributor@private.com'
  ssh://qtcontributor@codereview.qt.io/qt/qtbase HEAD:refs/for/stable
 Counting objects: 7, done.
 Delta compression using up to 2 threads.
 Compressing objects: 100% (3/3), done.
 Writing objects: 100% (4/4), 404 bytes, done.
 Total 4 (delta 2), reused 0 (delta 0)
 remote: Resolving deltas: 0% (0/2)
 To ssh://qtcontributor@codereview.qt.io/qt/qtbase
  * [new branch] HEAD-> refs/for/stable
 $

It is easy to have an overview of contributions in My Changes page. Contributor can view feedback on his or her contributions by accessing the change page and reading comments file-by-file. It is possible to reply on comments and have discussion about the code review in-line. Each time in-line comments or a review scores are published, a general comment can be added.

Contributor reads the feedback by following the steps:

1. Accessing My Changes page
2. Locating comments in the change page
3. Reading in-line comments
4. Publishing a reply or upload new patch set

Accessing My Changes page

It can be done by done by clicking "My" link on the top left corner and then selecting link "Changes".

Locating comments in the change

Comments are under each patch set. In the picture below the comments for Patch set 2 are examined

Reading in-line comments

Replies can be posted by clicking the comment like in the picture beneath:

Note that the comments are not actually posted until you publish them.

Note: do not reply to the notification mails you get from Gerrit. The mails you send this way will not be publicly visible and archived.

Reviewing contributions

The review process starts from choosing a change to review. After choosing a change, changed files can be viewed side-by-side and comments can be posted in-line to each file. Contributions are typically reviewed by approvers and possibly peer-reviewed by other contributors.

Following steps are needed to complete a code review:

1. Accessing Gerrit with web browser
2. Viewing change overview
3. Reviewing changed files
4. Publishing comments and reviewing results

Gerrit keeps track which files have been reviewed and which files have comments ready to be published. If an ongoing review is interrupted, reviewer can return later and continue from the point he was in before. Draft comments can be edited and deleted before they are published.

After review results are ready to be published, the reviewer continues to the publish comments screen with the Review button.

The Code Review category has 5 levels. A change can only be submitted after it receives +2 score. A change cannot be be submitted if it receives a -2 score.

Accessing Gerrit via web browser

Reviewer, typically approver, logs in to see own changes and those reviews that needs to be completed from the Code review dashboard like in the picture below:

Viewing change overview

Changes have several patch sets. When changes get updated after review, the patch set number increases.

Reviewing changed files

Changes are compared side-by-side. Reviewer can compare differences between specific patch sets by using Patch History.

Comments are posted by double clicking on a line. Comments are saved as drafts until they are published as in the pictures:

Publishing comments

Comments are published and a score is assigned to complete the review. By default, +2 for Code Review and +1 for Sanity Review categories is needed for a change to get merged. In the example +2 is selected and comments are awaiting publishing. A Sanity Review score should not be given unless the Sanity Bot made an error and needs to be overridden.

Downloading change

Easiest way to access change is to copy Download link from Gerrit to console, as it is done in the pictures below:

Reviewing change or run tests

Use git diff to compare changes. Build the code and run tests.

Publishing review result from command line

An alternative to browser-based review is to use the Gerrit ssh command line interface. Please do not do this, as scripting a step which is meant to be visual and interactive removes the additional safety net.

Updating a contribution with new code

Usually during review process a change must be updated with a new patch set. Contributor needs to update the change if it received some comments that require action or it did not merge with the branch tip. Each time when a change is updated, it gains a new patch set. Patch set numbering starts from 1. Change numbers will never change and they are unique.

To access the change, the original topic branch can be used or the change can be downloaded from Gerrit. Gerrit provides a quick way to copy the download link to clipboard and paste to console.

Updating a change is done by following steps:

1. Accessing change code
2. Modifying commit and adding Change-Id
3. Pushing updated change

After change is modified in a working tree, changes are committed with option —amend. The commit is uploaded back to Gerrit with target ref refs/for/<branch name> with updated Change-Id in commit message.

See step-by-step instructions provided below how to complete a change update:

Accessing change code

If the original commit is available, it is possible to continue editing that. Otherwise, just download the change by using the download link provided by Gerrit:

 $ git fetch ssh://qtcontributor@codereview.qt.io:29418/qt/qtbase
  refs/changes/19/419/1 && git checkout FETCH_HEAD
 From ssh://codereview.qt.io:29418/qt/qtbase
  * branch refs/changes/19/419/1-> FETCH_HEAD
 Note: checking out 'FETCH_HEAD'.
 
 You are in 'detached HEAD' state. You can look around, make experimental
 changes and commit them, and you can discard any commits you make in this
 state without impacting any branches by performing another checkout.  

 If you want to create a new branch to retain commits you create, you may
 do so (now or later) by using -b with the checkout command again. Example:

 git checkout -b new_branch_name

 HEAD is now at 9a006a3… My Feature
 $ git checkout -b changes/419
 Switched to a new branch 'changes/419'
 $

Modifying commit

Always make sure that the commit is based on the latest code from the Qt repository. To avoid merge errors, fetch and rebase the change before uploading a new version of the change.

Use option —amend to change the existing commit.

 $ git pull —rebase
 
 $ git commit —amend

Pushing updated change

Git push is done change ID as target ref. using to target ref

refs/for

. The correct target change is identified from the change-id footer in the commit message. After push, a new patch set will be created for the target change example can be seen below:

 $ vim src/foo.cc
 $ git add src/foo.cc
 $ git commit —amend
 [changes/419 2ea7773] My Feature
  1 files changed, 1 insertions(+), 0 deletions(-)
  create mode 100644 src/foo.cc
 $ git push origin HEAD:refs/for/master
 Counting objects: 6, done.
 Delta compression using up to 2 threads.
 Compressing objects: 100% (3/3), done.
 Writing objects: 100% (4/4), 419 bytes, done.
 Total 4 (delta 2), reused 0 (delta 0)
 remote: Resolving deltas: 0% (0/2)
 To ssh://qtcontributor@codereview.qt.io:29418/qt/qtbase.git
  * [new branch] HEAD -> refs/for/master
 $

Approving and abandoning

Approving and submitting a contribution

Depending on the project, an approved contribution will be submitted to the CI System (Qt 5) or a Git repository (Qt Creator). Changes are approved by reviewing and assigning them score that is high enough for submission. By default, changes required +2 for Code Review and +1 for Sanity Review categories to be approved. There are two ways to submit a change. If the project is using continuous integration system, changes will be merged to staging. Otherwise, they will be submitted directly to their destination branches.

• To submit a change to CI system press "Merge Patch Set 1 to Staging".
• To submit a change to Git repository press "Submit Patch Set 1"

In order to submit a change the user must have the required access rights. Only approvers and maintainers can submit changes. For contributors, it is enough to update the change until it passes the code review and CI building and testing.

If there are multiple relevant reviewers, you only need a +2 approval from one of them before staging. However if other reviewers have shown a specific interest in the patch, such as by repeated comments, then it is polite to give them some time to add a +1 or +2 before staging.

Abandoning a contribution

Those changes that should not be submitted can be abandoned. An abandoned change will disappear from open changes lists and is considered closed. Abandoned changes can be restored later if they become valid again or if they were abandoned by accident.

Abandoning changes is a normal operation that is used to maintain Gerrit and hide changes that will not make their way to Git repository, for any reason.

To abandon a change, owner, approver or maintainer can click "Abandon Change" button.

Finding new contributions by others

User can find changes by searching or by browsing projects and branches. Refer to Gerrit user's guide for detailed information how to use search queries. Links for change owner, project name and branch name in change tables can be used to access quick searches of the related changes.

Navigation bar at the top of the Gerrit web view can be used to quickly access

• User's own changes
• Changes the user is expected to review
• All open, merged and abandoned changes

Continuous integration and staging

Workflow

Gerrit has been slightly customized for the Qt project. The continuous integration system that is running regular builds and tests has been incorporated to the workflow. Instead of directly submitting changes, changes can be merged to a staging branch. There is a staging branch for each normal branch. Staging branches are maintained by Gerrit and are not visible to the contributors.

As part of customization, changes have new states. Changes in the New state are waiting for a review. After review, changes are merged to a staging branch and marked as staged. The continuous integration system will pick staged changes with regular intervals and move them to the Integrating stage. From the Integrating state changes are either submitted or moved back to the New state. If builds succeed and tests pass, submitted or merged their destination branch. Otherwise they are moved to the New state for further analysis. Contributor from whom the code originates from is expected to analyze why test and build phase failed and upload fixes.

Changes can still be submitted directly from new state, but only by users who have this specific access right in Gerrit.

Web UI and CLI

From a user's perspective, staging branch mechanism introduces only minor changes to the user interface. Instead of Submit button, "Merge to Staging" button is used.

In command line, instead of "—submit" argument, argument "—stage" is used.

$ ssh qtcontributor@codereview.qt.io gerrit review —stage
 2ea7773885dcc193abb35996f2bf7895051d68d3

Merging feature branches

Topics in Gerrit

Gerrit topics, or change sets, can be used as "feature branches". A topic is created when a special target ref is used. The syntax for the change set refspec is

refs/for/<branch name>/<topic name>

. It is often good enough to push a set of commits for review to a topic. However, if the contributor intends to work with others on a long-living branch the Gerrit Administrator should be contacted for a new branch that can be visible in Gerrit. Also the QA team has to be contacted so they can include the new branch in the CI system builds. This way the code can be reviewed already when working on it in the branch.

Merging feature branches

Merges between feature branches and the mainline are like all other commits and are pushed, reviewed and staged the usual way. However, only 'Merge Masters' can push merge commits. User may recruit the merge master from outside project team if it they do not have person knowledgeable on Git available. Note: Do not create a merge from commits which have not been integrated yet.

Merging branches Alien to Gerrit

This should not happen often. Nevertheless, only a merge commit should be pushed in this case. 'Git Administrator' can be asked to import the branch into Gerrit.

Access rights

Access rights are defined in the group level

In Gerrit, access rights are defined in the group level. Users are placed to different groups by the Gerrit administrator. Access rights are used to control the following operations.

• Access to projects and changes in these projects
• Review a change
• Merge to staging
• Submit

Access to projects, and changes they contain, can be limited to certain groups. Users outside the selected groups cannot see projects or any data belonging to these projects.

Review rights can be limited only to selected users, for example project members. User must have review access right to publish review comments.

Merge to staging and submit access rights are needed to move a change forward in the workflow.

Providing feedback about the set up

Report Bugs specific to our setup to "the bugtracker":http://bugreports.qt.nokia.com/browse/QTQAINFRA/component/19470 and any Gerrit issues "directly upstream":http://code.google.com/p/gerrit/issues/list.