Working with Gerrit¶
Follow these instructions to collaborate on Hyperledger Fabric through the Gerrit review system.
Gerrit assigns the following roles to users:
- Submitters: May submit changes for consideration, review other code changes, and make recommendations for acceptance or rejection by voting +1 or -1, respectively.
- Maintainers: May approve or reject changes based upon feedback from reviewers voting +2 or -2, respectively.
- Builders: (e.g. Jenkins) May use the build automation infrastructure to verify the change.
Maintainers should be familiar with the review process. However, anyone is welcome to (and encouraged!) review changes, and hence may find that document of value.
There’s a very useful tool for working with Gerrit called git-review. This command-line tool can automate most of the ensuing sections for you. Of course, reading the information below is also highly recommended so that you understand what’s going on behind the scenes.
We have created a sandbox project to allow developers to familiarize themselves with Gerrit and our workflows. Please do feel free to use this project to experiment with the commands and tools, below.
Getting deeper into Gerrit¶
A comprehensive walk-through of Gerrit is beyond the scope of this document. There are plenty of resources available on the Internet. A good summary can be found here. We have also provided a set of Best Practices that you may find helpful.
Working with a local clone of the repository¶
To work on something, whether a new feature or a bugfix:
Open the Gerrit Projects page
Select the project you wish to work on.
Open a terminal window and clone the project locally using the
Clone with git hookURL. Be sure that
sshis also selected, as this will make authentication much simpler:
git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/
Note: if you are cloning the fabric project repository, you will
want to clone it to the
so that it will build, and so that you can use it with the Vagrant
- Create a descriptively-named branch off of your cloned repository
cd fabric git checkout -b issue-nnnn
- Commit your code. For an in-depth discussion of creating an effective commit, please read this document on submitting changes.
git commit -s -a
Then input precise and readable commit msg and submit.
- Any code changes that affect documentation should be accompanied by corresponding changes (or additions) to the documentation and tests. This will ensure that if the merged PR is reversed, all traces of the change will be reversed as well.
Submitting a Change¶
Currently, Gerrit is the only method to submit a change for review.
Note: Please review the guidelines for making and submitting a change.
Use git review¶
Note: if you prefer, you can use the git-review tool instead of the following. e.g.
Add the following section to
.git/config, and replace
with your gerrit id.
[remote "gerrit"] url = ssh://<USERNAME>@gerrit.hyperledger.org:29418/fabric.git fetch = +refs/heads/*:refs/remotes/gerrit/*
Then submit your change with
$ cd <your code dir> $ git review
When you update your patch, you can commit with
git commit --amend,
and then repeat the
git review command.
Not Use git review¶
When a change is ready for submission, Gerrit requires that the change be pushed to a special branch. The name of this special branch contains a reference to the final branch where the code should reside, once accepted.
For the Hyperledger Fabric repository, the special branch is called
To push the current local development branch to the gerrit server, open a terminal window at the root of your cloned repository:
cd <your clone dir> git push origin HEAD:refs/for/master
If the command executes correctly, the output should look similar to this:
Counting objects: 3, done. Writing objects: 100% (3/3), 306 bytes | 0 bytes/s, done. Total 3 (delta 0), reused 0 (delta 0) remote: Processing changes: new: 1, refs: 1, done remote: remote: New Changes: remote: https://gerrit.hyperledger.org/r/6 Test commit remote: To ssh://LFID@gerrit.hyperledger.org:29418/fabric * [new branch] HEAD -> refs/for/master
The gerrit server generates a link where the change can be tracked.
Optionally, you can add reviewers to your change.
To specify a list of reviewers via the command line, add
%firstname.lastname@example.org to your push command. For example:
git push origin HEAD:email@example.com,firstname.lastname@example.org
Alternatively, you can auto-configure GIT to add a set of reviewers if your commits will have the same reviewers all at the time.
To add a list of default reviewers, open the :file:
in the project directory and add the following line in the
[ branch “master” ] section:
[branch "master"] #.... push = HEAD:email@example.com,firstname.lastname@example.org`
Make sure to use actual email addresses instead of the
@email.com and @notemail.com addressses. Don’t forget to replace
origin with your git remote name.
Reviewing Using Gerrit¶
- Add: This button allows the change submitter to manually add names of people who should review a change; start typing a name and the system will auto-complete based on the list of people registered and with access to the system. They will be notified by email that you are requesting their input.
- Abandon: This button is available to the submitter only; it allows a committer to abandon a change and remove it from the merge queue.
- Change-ID: This ID is generated by Gerrit (or system). It becomes useful when the review process determines that your commit(s) have to be amended. You may submit a new version; and if the same Change-ID header (and value) are present, Gerrit will remember it and present it as another version of the same change.
- Status: Currently, the example change is in review status, as indicated by “Needs Verified” in the upper-left corner. The list of Reviewers will all emit their opinion, voting +1 if they agree to the merge, -1 if they disagree. Gerrit users with a Maintainer role can agree to the merge or refuse it by voting +2 or -2 respectively.
Notifications are sent to the email address in your commit message’s Signed-off-by line. Visit your Gerrit dashboard, to check the progress of your requests.
The history tab in Gerrit will show you the in-line comments and the author of the review.
Viewing Pending Changes¶
Find all pending changes by clicking on the
All --> Changes link in
the upper-left corner, or open this
If you collaborate in multiple projects, you may wish to limit searching to the specific branch through the search bar in the upper-right side.
Add the filter project:fabric to limit the visible changes to only those from Hyperledger Fabric.
List all current changes you submitted, or list just those changes in
need of your input by clicking on
My --> Changes or open this