Gerrit Guide¶

Submitting a New Patch¶

1. On your machine, open a shell and switch to the directory with the git repository. Assuming you are using the docs repository:

   cd docs
   

2. To remove any dependencies on other files you are working on, check out the appropriate branch:

   git checkout ${remote_branch_name}  # will switch to the branch
   

   Note

   normally, ${remote_branch_name} should be master, but during a release, the master will switch to stable/${release_name}, e.g., stable/carbon at some point. Also, if you are updating an existing release check out that branch.

   Note

   If you see an error like``error: pathspec ‘stable/carbon’ did not match any file(s) known to git.``, try this command instead:

   git checkout -b ${remote_branch_name} origin/${remote_branch_name}
   

   Note

   This should only be necessary once.

3. Get a copy of the latest files from the server:

   git pull                                      # will get all the changes from the server
   git reset --hard origin/${remote_branch_name} # (optional) will undo any local changes you've
                                                 # (accidentally) made to ${remote_branch_name}
   

4. Create a new branch for your work:

   git checkout -b ${local_branch_name}
   

   Note

   Spaces are not allowed in ${local_branch_name}.

5. Create new files or edit existing files, as needed.

6. Commit the files you have worked on:

   • If you’ve created any new files, run:

     git add ${filename}
     

   • To commit existing files you edited, run:

     • git commit -as

     • Your default terminal text editor will open.

       Note

       The -as options instruct git to commit all of the files you have edited (-a) and sign your commit request with your email address and name (-s). The sign-off is to indicate that you agree with this statement:

       Developer's Certificate of Origin 1.1
       
          By making a contribution to this project, I certify that:
       
          (a) The contribution was created in whole or in part by me and I
              have the right to submit it under the open source license
              indicated in the file; or
       
          (b) The contribution is based upon previous work that, to the best
              of my knowledge, is covered under an appropriate open source
              license and I have the right under that license to submit that
              work with modifications, whether created in whole or in part
              by me, under the same open source license (unless I am
              permitted to submit under a different license), as indicated
              in the file; or
       
          (c) The contribution was provided directly to me by some other
              person who certified (a), (b) or (c) and I have not modified
              it.
       
          (d) I understand and agree that this project and the contribution
              are public and that a record of the contribution (including all
              personal information I submit with it, including my sign-off) is
              maintained indefinitely and may be redistributed consistent with
              this project or the open source license(s) involved.
       

   • Add a brief description of the changes you have made to the beginning of the commit request and then save the request.

     Note

     Writing good git commit messages is important and relatively easy, but it’s good to familiarize yourself with general guidelines like this How to Write a Git Commit Message Guide.

     Important

     We have linters that check for some of the style guides including that the first line of a git commit message is 50 characters or less. So, make sure to follow that one.

7. Submit your files for review:

   • git review
   • You will receive 2 emails from Gerrit Code Review: The first indicating that a build to incorporate your changes has started; and the second indicating whether the build was created successfully.

8. Determine your patch’s change number:

   • Open either of the emails you received after submitting your files for review.

   • Locate the following line in the terminal: To view, visit <patch URL>

     Note

     The number at the end of this URL is your patch’s change number. You will need this in order to make updates to the patch later.

Updating an Existing Patch¶

1. On your machine, open a shell and switch to the directory containing the repository: cd ${repository_name}, e.g., cd docs

2. Download the patch you want to update: git review -d ${change_number}

3. (Optional) View information on the latest changes made to that patch:

   To view the files that were edited, run git show

   To view a listing of the files that were edited and the number of lines in those files that were edited, run git show --stat

4. Make the necessary changes to the patch’s files.

5. Commit your changes:

   1. run git commit -a --amend

   2. Update the current patch description and then save the commit request.

      Note

      If you feel as though you did enough additional work on the patch that you should be mentioned, add your name in the footer with a line like Co-Authored-By: First Last <email>.

6. Submit your files for review:

   git review

You will receive 2 emails from Gerrit Code Review: the first indicating that a build to incorporate your changes has started; and the second indicating whether the build was created successfully.

Pre-review¶

Many times, change authors will want to push changes to Gerrit before they are actually ready for review. This is a good practice and is encouraged. It has been the experience of Integration/* so far that pushing early and often tends to reduce the amount of work overall.

To mark an uploaded change as not ready for attention by committers and interested contributors (in order of preference), either mark the Gerrit a draft (by adding a -D to your git review command), vote -1 on it yourself or modify the commit message with “WIP” (“Work in Progress”).

Don’t add committers to the Reviewers list for a change while it’s in the pre-review state, as it adds noise to their review queue.

Review¶

Once an author wants a change to be reviewed, they need to take some actions to put it on the radar of the committers.

If the change is marked as a draft, you’ll need to publish it. This can be done from the Gerrit web UI.

Gerrit Web UI button to publish a draft change.

Remove your -1 vote if you’ve marked it with one. If you think the patch is ready to be merged, vote +1. If there isn’t an automated job to test your change and vote +1/-1 for Verified, you’ll need to do as much testing yourself as possible and then manually vote +1 to Verified. You can also vote +1 for Verified if you’ve done testing in addition to any automated tests. Describing the testing you did or didn’t do is typically helpful.

Gerrit voting interface, exposed by the Reply button.

Once the change is published and you’ve voted for it to be merged, add the people who need to review/merge the change to the Gerrit Reviewers list. For Integration/Packaging, add all of our committers (Daniel Farrell, Jamo Luhrsen, Thanh Ha) in addition to any other relevant contributors. The auto-complete for this Gerrit UI field is somewhat flaky, but typing the full name from the start typically works.

Gerrit Reviewers list with Int/Pack committers added

Reviewers will give feedback via Gerrit comments or inline against the diff.

Gerrit inline feedback about a typo

Updated versions of the proposed change should be pushed as new patchesets to the same Gerrit, either by the original submitter or other contributors. Amending proposed changes owned by others while reviewing may be more efficient than documenting the problem, -1ing, waiting for the original submitter to make the changes, re-reviewing and merging.

Changes can be downloaded for local manipulation and then re-uploaded with updates via git-review. See Updating an Existing Patch above. Once you have re-uploaded the patch the Gerrit web UI for the proposed change will reflect the new patcheset.

Gerrit history showing a patch update

Reviewers will use the diff between the last time time they gave review and the current patchset to quickly understand updates, speeding the code review process.

Gerrit diff menu

Iterative feedback continues until consensus is reached (typically: all active reviewers +1/+2 and no -1s, definitely no -2s), at least one committer +2s and a committer merges the change.

Gerrit code review votes

Merge¶

Once a patch has gotten a +2 from a committer and they have clicked the submit button the project’s merge job should run and publish the project’s artifacts to Nexus. Once this is done other projects will be able to see the results of that patch.

This is particularly important when merging dependent patches across multiple projects. You will need to wait for the merge job to run on one patch before any patches in other projects depending on it will successful verify.

Creating an OpenDaylight Account¶

1. Using a Google Chrome or Mozilla Firefox browser, go to https://git.opendaylight.org/gerrit

   The main page shows existing Gerrit requests. These are patches that have been pushed to the repository and not yet verified, reviewed, and merged.

   Note

   If you already have an OpenDaylight account, you can click Sign In in the top right corner of the page and follow the instructions to enter the OpenDaylight page.

   

   Signing in to OpenDaylight account

2. If you do not have an existing OpenDaylight account, click Account signup/management on the top bar of the main Gerrit page.

   The WS02 Identity Server page is displayed.

   

   Gerrit Account signup/management link

3. In the WS02 Identity Server page, click Sign-up in the left pane.

   There is also an option to authenticate your sign in with OpenID. This option is not described in this document.

   

   Sign-up link for Gerrit account

4. Click on the Sign-up with User Name/Password image on the right pane to continue to the actual sign-up page.

   

   Sign-up with User Name/Password Image

5. Fill out the details in the account creation form and then click Submit.

   

   Filling out the details

You now have an OpenDaylight account that can be used with Gerrit to pull the OpenDaylight code.

Generating SSH keys for your system¶

You must have SSH keys for your system to register with your Gerrit account. The method for generating SSH keys is different for different types of operating systems.

The key you register with Gerrit must be identical to the one you will use later to pull or edit the code. For example, if you have a development VM which has a different UID login and keygen than that of your laptop, the SSH key you generate for the VM is different from the laptop. If you register the SSH key generated on your VM with Gerrit and do not reuse it on your laptop when using Git on the laptop, the pull fails.

For a system running Ubuntu operating system, follow the steps below:

1. Run the following command:

   mkdir ~/.ssh
   chmod 700 ~/.ssh
   ssh-keygen -t rsa
   

2. You are prompted for a location to save the keys, and a passphrase for the keys.

   This passphrase protects your private key while it is stored on the hard drive. You must use the passphrase to use the keys every time you need to login to a key-based system:

   Generating public/private rsa key pair.
   Enter file in which to save the key (/home/b/.ssh/id_rsa):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in /home/b/.ssh/id_rsa.
   Your public key has been saved in /home/b/.ssh/id_rsa.pub.
   

Your public key is now available as .ssh/id_rsa.pub in your home folder.

Registering your SSH key with Gerrit¶

1. Using a Google Chrome or Mozilla Firefox browser, go to https://git.opendaylight.org/gerrit.

2. Click Sign In to access the OpenDaylight repository.

   

   Signin in to OpenDaylight repository

3. Click your name in the top right corner of the window and then click Settings.

   The Settings page is displayed.

   

   Settings page for your Gerrit account

4. Click SSH Public Keys under Settings.

5. Click Add Key.

6. In the Add SSH Public Key text box, paste the contents of your id_rsa.pub file and then click Add.

   

   Adding your SSH key

To verify your SSH key is working correctly, try using an SSH client to connect to Gerrit’s SSHD port:

$ ssh -p 29418 <sshusername>@git.opendaylight.org
Enter passphrase for key '/home/cisco/.ssh/id_rsa':
****    Welcome to Gerrit Code Review    ****
Hi <user>, you have successfully connected over SSH.
Unfortunately, interactive shells are disabled.
To clone a hosted Git repository, use: git clone ssh://<user>@git.opendaylight.org:29418/REPOSITORY_NAME.git
Connection to git.opendaylight.org closed.

You can now proceed to either Pulling, Hacking, and Pushing the Code from the CLI or Pulling, Hacking, and Pushing the Code from Eclipse depending on your implementation.

Setting up gpg-agent on a Mac¶

1. Install gpg-agent and pinentry-mac using brew:

   brew install gpg-agent pinentry-mac
   

2. Edit your ~/.gnupg/gpg.conf contain the line:

   use-agent
   

3. Edit your ~/.gnupg/gpg-agent.conf to something like:

   use-standard-socket
   enable-ssh-support
   default-cache-ttl 600
   max-cache-ttl 7200
   pinentry-program /usr/local/bin/pinentry-mac
   

4. Edit your .bash_profile or equivalent file to contain the following:

   [ -f ~/.gpg-agent-info ] && source ~/.gpg-agent-info
   if [ -S "${GPG_AGENT_INFO%%:*}" ]; then
     export GPG_AGENT_INFO
   else
     eval $( gpg-agent --daemon --write-env-file ~/.gpg-agent-info )
   fi
   

5. Kill any stray gpg-agent daemons running:

   sudo killall gpg-agent
   

6. Restart your terminal (or log in and out) to reload the your .bash_profile or equivalent file

7. The next time a Git operation makes a call to gpg, it should use your gpg-agent to run a GUI window to ask for your passphrase and give you an option to save your passphrase in the keychain.