Geekly Articles each Day
📜 ⬆️ ⬇️

"Gerrit Code Review": a quick guide with pictures


Red and Blue Chair by Gerrit Rietveld (1918)

Badoo has a department for C / C ++ programmers. The department is rather small, and therefore its employees usually work on different projects that intersect with each other only in exceptional cases.

One of the negative consequences of this situation is the bus factor , which tends to unity. To solve this and other problems, it was decided to experimentally implement a code revision system (code review): assign one developer an auditor to another and thus acquaint him with the code, and at the same time improve the quality of the latter.
')
The main requirements for the code revision system were formed:

After reviewing several options ( Rietveld , ReviewBoard , Gerrit ), it seemed to us that Gerrit is the easiest way to install and prepare for work. Therefore, we decided to make a small guide on the use of this system.

History tour


As is often the case in the open source world, Gerrit appeared as a patchset for another project. The original goal was to add support for ACL in Rietveld - a code revision system written by Python by Python author Guido van Rossum (niderl. Guido van Rossum ). Due to the fact that Guido did not want to complicate the Rietveld code, there appeared a fork of the latter called Gerrit.

Later, Gerrit was rewritten from Python to Java and thus became a completely independent project. At the moment, Gerrit is used by companies and projects like eBay, Sony, Couchbase, MediaWiki, Rockbox and Qt, but the most famous Gerrit user is probably an Android project, for which Gerrit and was written.

By the way, here you can find an explanation of the project name: http://en.wikipedia.org/wiki/Gerrit_Rietveld .

Principle of operation


Development using Gerrit is as follows:

Using the access control system in Gerrit, you can prevent the developer from sending changes to bypass the code revision and leave this right only to the auditor, which is very suitable for us: this means that the auditor will see all the changes and (theoretically, of course) will be familiar with all the project code.

Installation and Setup


The Gerrit distribution is distributed as a WAR archive , so its installation looks quite simple: create a database (MySQL, PostgreSQL and embedded H2 are supported), add a user to the system, initialize the site and set up a web server. Badoo traditionally uses nginx , so we customized it. In nginx.conf, it looks like this:

server { listen 80; server_name gerrit; rewrite ^(.*) https://$server_name$1 permanent; } server { listen 443; server_name gerrit; add_header Strict-Transport-Security max-age=15768000; ssl on; ssl_certificate /local/nginx/conf/cert/gerrit.crt; ssl_certificate_key /local/nginx/conf/cert/gerrit.key; ssl_session_timeout 5m; ssl_session_cache shared:SSL:1m; ssl_protocols TLSv1; ssl_ciphers HIGH:!ADH; ssl_prefer_server_ciphers on; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header Host $host; auth_basic "Restricted"; auth_basic_user_file htpasswd; } }

The installation is described in detail in the documentation , so we will not go into the details; instead, let's go straight to the description of the Gerrit web interface.

This is what the first Gerrit page looks like right after the initial installation:



It’s time to say that Gerrit currently does not support any local authorization. There is support for OpenID, HTTP Basic / Digest Authentication and Computer Associates Siteminder (commercial “single sign-on” solution), and that’s it. The decision to use external authorization is quite logical for open participation projects, but in our case HTTP Auth is the only possible option, despite its dubious convenience.

Getting started with Gerrit


After registering in the system by adding e-mail and public key for SSH, you can get to work.

First you need to create a new project in Gerrit. Unfortunately, there is no possibility to do this via the web interface. In the process of writing the article, Gerrit 2.3 was released, in which this omission was corrected and, finally, you can create a new repository directly from the web interface: Admin \ Projects \ Create new project:



In the form of creating a project, you can immediately choose which rights to inherit - this is useful when creating projects with sample rights. By default, common rights are inherited ( All-Projects ).

You can also specify additional project settings:



Go to the console and directly to work with Git:
 $ git clone ssh://gerrit:29418/test_project.git Cloning into test_project... warning: remote HEAD refers to nonexistent ref, unable to checkout.

The warning can be ignored, it is fully justified (the repository does not contain any revisions), but for us it is completely useless. Do not be surprised at the strange port 29418 - Gerrit has its own SSH server and its own Git implementation (JGit in Java).

Create the first file and the first revision of the code:
 $ cd test_project $ echo “test” > README $ git add README $ git commit README -m “first commit” [master (root-commit) b1f69cf] first commit 1 files changed, 1 insertions(+), 0 deletions(-) create mode 100644 README

The default rights for all projects do not allow sending changes to the server bypassing the code revision system, therefore the command `git push origin master` at this stage will end with the following error:
 $ git push origin master Counting objects: 3, done. Writing objects: 100% (3/3), 224 bytes, done. Total 3 (delta 0), reused 0 (delta 0) To ssh://gerrit:29418/test_project.git ! [remote rejected] master -> master (can not create new references) error: failed to push some refs to 'ssh://gerrit:29418/test_project.git'

And this is correct, because our goal is to make the auditor always review and approve the code. Therefore, it is necessary to send changes to the server as follows:
 $ git push origin HEAD:refs/for/master Counting objects: 3, done. Writing objects: 100% (3/3), 224 bytes, done. Total 3 (delta 0), reused 0 (delta 0) remote: remote: New Changes: remote: https://gerrit/337 remote: To ssh://gerrit:29418/test_project.git * [new branch] HEAD -> refs/for/master

Here it should be noted that the command syntax, to put it mildly, is not the most convenient. However, this is easily corrected with this setting:

 $ git config branch.master.merge refs/for/master

Now the change was successfully transferred to the server, but it did not immediately hit the repository. Instead, a change with ID 337 was created on the server, which can be viewed and approved via the Gerrit web interface (note the link in the Gerrit output):



In this screenshot you can see all the parameters and actions of a particular change. If you wish, you can add an additional auditor (in this case, he will receive a notice), review ( Review ) or reject the change ( Abandon Change ). There are also ready-made command texts for a quick “copy / paste”: checkout of the project, pull, cherry-pick, or receiving a patch of this change.

Naturally, you can add comments to each change, this is done on the Review page - let's move on to it.



Here you can see directly the form of assessment changes. Please note that in this snapshot there are only 3 (-1 / 0 / + 1) possible estimates of 5 (-2 / -1 / 0 / + 1 / + 2). This happened because our test user Philip J. Fry does not have a decisive vote on this project.

Ratings -1 / + 1 have a recommendatory status, they do not affect the acceptance or non-acceptance of the change, therefore, by default, all registered users have the right to set them. Estimates of -2 and +2 are decisive (no, -1 / + 1 are not cumulative, but this can be done using an automatic script ) - any assessment of +2 allows you to apply the change, any assessment of -2 blocks the change and it cannot be applied until its removal (despite the presence of any amount of +2). A detailed description of the voice system is in the documentation .

Let's give the deciding right to our user and at the same time illustrate the rights system in Gerrit. First you need to create a group, which we allow to evaluate the changes in our project. To do this, go to the Groups tab, where at the bottom we find the form for creating a new group. Our test user will be automatically added to the members of this group, but if you need to add someone else, just start typing his name, and Gerrit will show you a hint:



After this, the new group Test Reviewers must be granted the right to accept or reject changes to this project. In the Projects tab, select our project, the Access tab, then click the Edit button:



On this page you can change the rights and their parameters. In our case, we grant the right to rate ( Label Code-Review ) from -2 to +2 to the Test Reviewers group, and this right applies to all branches of the project. At the same time we will give the same group the right to apply changes ( Submit ). After adding new privileges, return to the change page. Now it displays more options:



As you can see, first of all, our user now has the opportunity to rate any change, including decisive +2 and -2 . And secondly, there is a button Publish and Submit , which allows our user to apply the change.

Privilege system


Gerrit has a complex privilege system. Each privilege can be given to a group (or groups) of users, and at the same time limit its radius of action to the framework of a specific branch of the repository. At the same time, administrators can create new privileges (an example of copyright verification is given in the documentation ).

The list of privileges that are available by default:
* Label Verified - the ability to mark changes as checked.
This category was added specifically for the Android project and means that the change does not break the project build and passes tests. This category was not useful to us, how to remove it is described in the documentation .
* Label Code Review - directly revision of the code with the ability to specify a range of available ratings (from -2 to +2).
* Create reference - the ability to create links, branches and tags in the repository.
* Forge author / Forge committer / Forge server - the ability to "forge" changes from other people. Gerrit usually requires that the changeor's e-mail address matches one of the registered addresses, but this can be circumvented with this privilege. Usually, it is only needed when importing an already existing repository into Gerrit.
* Owner - gives the right to issue / change privileges for this project, change the project description, delete and create branches in the repository (only through the web interface).
* Push - the right to write changes (eng. Commit ) to the repository. The privilege to commit to refs / * gives the right to add changes directly to the repository, bypassing the code revision system.
* Push Merge Commit - addition to Push, allowing the user to conduct merging of branches.
* Push Annotated Tag - another addition to Push, this time allowing to add tags to the repository.
* Read - the right to read the code in the repository, changes in the system and comments to them; by default, allowed to all users who are registered in the system.
* Submit - the right to apply changes to the repository.

Based on our goals, we selected the following optimal configuration for our projects:



Thus, committers can add branch merges to the part of the repository that is intended for code revision (but not directly to the repository), create tags and the changes themselves for further consideration. And auditors can review changes and apply them.

Instead of conclusion


Gerrit left a rather mixed impression on the author of this article.

On the one hand, some of its possibilities are not obvious, inconvenient, or do not exist at all, which in general strongly resembles that strange chair, which is shown in the title of the article. For example, you cannot delete a group from the interface, the project code is not possible to see, until recently it was impossible to even create a new project from the browser, only via SSH. And many administrative functions have to be done directly in the database, which is fraught with problems. The absence of any user management in Gerrit itself is not happy either. In general, there are many shortcomings, which confirms this list .

On the other hand, Gerrit performs its immediate function successfully, and after some time spent on the initial introduction and configuration, it does not require any attention from the developers.

In conclusion, we must also recognize that the original goal with which we implemented Gerrit was never fulfilled - it is useless to try to “acquaint” the developer’s code, who only views it, but does not participate in the discussion of the project and does not understand why the code is what he is. But the code revision system works fine in the case of an already existing project, where developers can be divided into “owners” who are responsible for the project as a whole and consider changes by others, and “participants” who can send their changes to the project without being able to apply them directly. Therefore, despite all its flaws, our department has adopted Gerrit and successfully uses it for all current projects.

Anton Dovgal, developer
Badoo company

Source: https://habr.com/ru/post/147508/

More articles:


All Articles