User Tools

Site Tools


how_to_use_gerrit

How to use IoTivity Gerrit

Gerrit is a web-based code review tool built to work together with the git version control system. Gerrit offers side-by-side difference viewing and inline commenting to make the mechanics of code reviewing painless. The basic concept is you make changes to a local branch and git push the commits to the iotivity repository. Gerrit intercepts these changes and turns them into a review page, giving you back a link to a web page. From here you can request reviews, as well as request the Jenkins autobuild system to build with your change applied - normally reviewers will want to see that your commit will apply before approving it.

Setup

Configure ssh access

Step 1: Create SSH keys

If you don't already have an ssh keypair, create one. On a Linux system, this command from a shell will do it:

 $ ssh-keygen -t rsa -C "Your name <your_email_address>"

Example for John Doe:

 $ ssh-keygen -t rsa -C "John Doe john.doe@example.com"

After pressing the Enter key at several prompts, an ssh key-pair will be created in ~/.ssh as id_rsa and id_rsa.pub.

Step 2: Setting up SSH

Edit ~/.ssh/config using your favorite text editor and add these lines:

  Host gerrit.iotivity.org
      Hostname "gerrit.iotivity.org"
      IdentityFile ~/.ssh/id_rsa
      User <Linux Foundation ID>
      Port 29418

If you are lucky enough to not need a proxy, this should be enough. If you are inside a corporate network, a proxy is very likely to be needed. The details of what will work are likely to vary, but using netcat (nc commend) or connect has worked for many. Here are a couple of examples for adding to the stanza for the gerrit server:

      ProxyCommand nc -X5 -x <proxy-address>:<port> %h %p
      
      ProxyCommand connect -S <proxy-address>:<port> %h %p
Step 3: Upload SSH pubkey to Gerrit and Register personal info

Log in to IoTivity Gerrit

Upload SSH pubkey to Gerrit

  Settings (top right) --> SSH Public Keys --> Add Key...

Paste your SSH public key there, and then click 'Add'. In the Gerrit UI, you can also register your email address and update your full name:

  Settings --> Contact Information --> Register New Email...
  Settings --> Contact Information --> Full Name..

After you register the email, you will receive an email which contains a link. Please copy the link to your browser to activate the account.

Step 4: Verify your SSH connection

You can verify your Gerrit connection by executing this command:

 $ ssh gerrit.iotivity.org

If your settings are correct, you will see the message beginning with the below (and then telling you how to proceed). If not, check SSH proxy and SSH public key on Gerrit.

  ****    Welcome to Gerrit Code Review    ****

Configure Git for Gerrit Access

Once you have configured your information with Gerrit, you need at a minimum to configure your local git.

 $ git config --global user.name "First_Name Last_Name"
 $ git config --global user.email "account@host"

For example:

 $ git config --global user.name "John Doe"
 $ git config --global user.email "john.doe@example.com"

Note: It is recommended that you use the same email address you used for your Gerrit account for the “user.email” setting. Make sure you have developer access first.

Cloning Project Source

The list of IoTivty projects is found on the Projects and Functions page. Please read and remeber where to find this page: to get a change approved, you will have to get the appropriate maintainer/sub-maintainer to vote +2 on it, which means you need to know who to invite to review.

The project list is also available by query:

  $ ssh gerrit.iotivity.org gerrit ls-projects | grep <Gerrit_Project>

Clone the required package by executing the following command:

  $ git clone ssh://gerrit.iotivity.org/<Gerrit_Project>

An example is shown below:

  $ git clone ssh://gerrit.iotivity.org/iotivity

You will need to get an iotivity-specific commit script set up on your system - the hook generates a ``Change-Id`` line whenever you commit a change, and Gerrit tracks submissions by ``Change-Id`` so this is mandatory. Note this is placed in your working tree so only applies to activity on this tree, not all git operations.

  $ cd iotivity
  $ scp gerrit.iotivity.org:hooks/commit-msg .git/hooks/

Important Gerrit Operations

Submit a patch for review

See the page on submitting changes to Gerrit.

Pull a patch from Gerrit

If you want to pull a patch from Gerrit, perhaps to verify it, or modify and resubmit, Gerrit will simplify things by showing what you need.

  • Copy the command to download the patch of interest from the Gerrit review page.
  • Paste the command into command line.

Note: sometimes you may get an error that looks like:

 ssh: connect to host gerrit.iotivity.org port 29418: Bad file number
 fatal: Could not read from remote repository.

Please make sure you have the correct access rights and that the repository exists.

Reviewing Patches on Gerrit

Tips

1. Watch a project

If you are interested in a package that has an important relation to yours, like a dependency, then you can watch those projects. You will receive a notification when a patchset is uploaded to Gerrit. Adjust the Watched Projects settings to monitor projects.

  Settings (top right) --> Watched Projects --> input Project Name -> click 'Watch'

You can restrict to certain files only in a given project by providing a regular expression match in the “Only If” field. Example:

  file:^examples/.* OR file:^ocsdk/occoap/.* OR file:^.*/SConscript$

2. Replace a Patch Set

To add a new patch set that replaces an existing patch set with an updated version of the same logical modification, send the new commit to the same branch the previous one was sent to. The command is the same as described above for the initial push. Make sure the Commit-id has not changed. If you have worked in a local branch, and kept it after pushing, you should be able to update your patch set by editing, running git add to add the changed files, then git commit –amend to update your change, before pushing.

3. Rebase a Patch set

It frequently happens that while your patch is being reviewed, other changes are accepted to the target branch which would cause a merge problem with your patch. Gerrit will often detect this, and in the web interface show you a message in red, “cannot merge”. If you manually go through the steps to merge, the merge will become a new commit, and the commit ID will change. Since Gerrit works of the commit ID, when you now push, it will look like a new change. In order to avoid this, you can rebase instead, and follow the instructions in the previous step. Gerrit also has a button in the web interface to attempt a rebase, which if it works, is perhaps easier than fiddling manually - but then the local branch containing your work will need to be updated.

4. Command Line Tools

A number of Gerrit commands can be sent through ssh. The Review command is of particular interest:

  ssh -p <port> <host> gerrit review [--message <MESSAGE>] [--verified <N>] [--code-review <N>] [--abandon] {COMMIT | CHANGEID,PATCHSET}...

The Gerrit documentation site has detailed documentation on "gerrit review". The full set of gerrit commands is also available.

There is is also a tool developed for the OpenStack project called git-review which attempts a nicer interface to working with gerrit than issuing ssh commands. TODO: add some examples.

Patch Reviewing

You can review patch sets by using the command line, for example, to verify, approve, and submit the patch c0ff33:

  $ ssh gerrit.iotivity.org gerrit review --verified=+1 --code-review=+2 --submit -m "Comment" c0ff33
   

Please use the web interface instead if you have line-by-line comments.

Abandon a Patch

To drop an uploaded patch, just click the Abandon button in the Gerrit Web UI or use the command line interface as in this example:

$ ssh gerrit.iotivity.org gerrit review –abandon -m “Explanation for abandoning” c0ff33

More detailed instructions

Gerrit has a documentation tab in the web UI, and a '–help' command from the command line:

  $ ssh gerrit.iotivity.org gerrit --help
how_to_use_gerrit.txt · Last modified: 2017/05/19 14:39 by Mats Wichmann