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.

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 below. If not, check SSH proxy and SSH public key on Gerrit.

  • * Welcome to Gerrit Code Review **

Config Git for Gerrit Access

Once you have configured your information with Gerrit, you need 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 the commit-msg hook script set up on your system - this generates a Change-Id line whenever you commit a change, and Gerrit tracks by the Change-Id so this is mandatory.

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

Submit a patch to the Gerrit

See the page on submitting changes to Gerrit.

Pull a patch from the Gerrit

At times you want to pull a patch from Gerrit, probably to verify it or modify and resubmit. In order to pull a patch:

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

Note: some times 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 the Gerrit

Tips

1. Watch a project

If you're interested in a package that has an important relation to yours, like a dependency, then you can watch those projects. You can 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 it was sent to. The procedure is the same as described above for the initial pushing.

3. Command line Tools

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

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 set

To drop an uploaded patch, just click the Abandon button at Web UI or use the command example, as shown below, for example:

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

More detailed instructions

For detailed instructions, you can get information from the '–help' command:

     $ ssh gerrit.iotivity.org gerrit --help
how_to_use_gerrit.txt · Last modified: 2017/03/15 14:47 by Mats Wichmann