Introduction to Gerrit

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:

Cloning from repository

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

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

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.

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

Creating a topic branch

Keep code organized in topic branches. [git-scm.com] This is what Git excels in. “next-big-thing” is used as an example topic branch below:

Doing changes

Use your favorite editor to complete a coding task.

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:

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.

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.

When pushing to Gerrit, a typical refspec [git-scm.com] 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.

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. [gerrit.googlecode.com] Using cc option for receive-pack sends an e-mail notification to that user. Gerrit will avoid sending duplicate emails to the same user.

Reading contribution feedback

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 scor

Categories:

• Developing_Qt