|This page provides instructions for getting setup with and using the GerritHub code review tool.|
GerritHub is a code review tool developed by Google that integrates with GitHub. It provides an interface for creating an managing code reviews, which are initiated from a GitHub pull request.
Assumptions: This tutorial assumes that the user has an account on GitHub.
- Request your software lead to add you as a member of the 'Ocean Observatories Initiative' group on GitHub.
- Once you get a confirmation e-mail, go to https://github.com/oceanobservatories.
- Click on the 'People' link.
- Find yourself on the next page.
- Change your visibility from 'Private' to 'Public' (click on the 'make public' link).
Here are the steps to get started on GerritHub:
- Go to http://gerrithub.io/.
- Sign in using your GitHub credentials.
- Verify that your account profile is up-to-date.
- The next screen will allow you to select GitHub repositories to clone and replicate. We don't need to perform this step. Unselect anything that is checked. Go ahead and click 'Next'.
- You are now setup to start using GerritHub!
Note: In case of any difficulty with the above steps, there's a helpful video at https://www.youtube.com/watch?v=jeWTvDad6VM. Note that our instructions are slightly more specific than what's shown in the video.
In order to use GerritHub with GitHub, you need to 'squash' together commits before creating a pull request. The idea is to give developers flexibility to commit their work as they go, but in order to keep pull requests clean, we want developers to 'squash' together all of their commits into a single commit, which will be be the only commit the pull request will consist of. Squashing multiple commits into one avoids reviewers from going through the hassle of looking through multiple commits on Gerrit. Instead, they will be able to view a single diff comprising of all the 'squashed' commits together, against the version immediately preceding the first commit in the 'squash'.
This tutorial assumes the user has a working knowledge of GitHub and is able to commit and push changes onto their branch in a repository.
Here's a set of simple instructions to squash together commits:
- Say you have N commits you need to squash together.
- You will need to find the version no. for the (N+1)th most recent commit. For example, if you need to squash together your 2 most recent commits, you will need the version no. of your 3rd most recent commit. To find this number, on the command line, type
- This command will give you a list of commits you made. Find the (N+1)th most recent commit and copy the version no.
- Next, on the command line, do the following:
- A file will open up in a vi editor. Replace 'pick' on the second and subsequent lines with 'squash' or 'fixup'(if you want to get rid of logs for intermediate commits - makes it more clean!). Save and exit.
- Next, push the rebased version to github:
- Go to github.com, navigate to your branch in your repository, check the history of the file(s) for which you just squashed commits. Make sure your commits were merged into a single commit as expected.
Once you are satisfied that your commits got 'squashed' together correctly, create a new pull request on github.com. This pull request will be used to initiate a code review on GerritHub.
This section outlines the steps to initiate a code review, add reviewers, add comments to a review, and submit the review.
The following instructions outline how to create a code review in Gerrit using a GitHub pull request.
- Go to gerrithub.io
- Click on the 'Open Gerrit Code Review' button.
- Under the 'Github' menu, click on 'Pull Requests'.
- Select 'oceanobservatories' from the repository dropdown.
- You should see your pull request in the resulting list. Select your pull request and click the 'Next' button. You will see an 'Imported' confirmation with a green checkbox next to it. Click the 'Next' button again.
- The next page that opens up is called 'My Reviews'. This page can also be accessed using My->Changes.
- You will notice that your pull request shows up under 'Outgoing Reviews'. Gerrit automatically created a review from your pull request. Click the review to open it.
To add reviewers:
- Locate the 'Add' button next to 'Reviewers' towards the top of the review page, or the 'Change' page - which is how Gerrit likes to call it.
- Enter the reviewer's name/email and click the 'Add' button. You should now see the reviewer's name listed. They will be automatically notified via email.
- You should receive an email stating you've been requested to perform a code review. Open the link in this email to launch the code review.
- You should see a list of files for the code review. Click on the file you wish to review.
- You should see a diff of the changes on the next screen.
- To add a comment, click on a line and press 'c'. This should open a comment window. Hit 'save' to save your comment.
- Once you are done adding comments, click on the 'Reply' button at the top of the code review page.
- On the resulting dialog, you can add a message, and select +1 if you approve of the changes, or -1 if you disapprove. Click the 'Post' button to submit your review.