github.com/adnan-c/fabric_e2e_couchdb@v0.6.1-preview.0.20170228180935-21ce6b23cf91/docs/Gerrit/gerrit.md (about)

     1  # Working with Gerrit
     2  
     3  Follow these instructions to collaborate on the Hyperledger Fabric Project
     4  through the Gerrit review system.
     5  
     6  Please be sure that you are subscribed to the [mailing
     7  list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric) and of
     8  course, you can reach out on [chat](https://chat.hyperledger.org/) if
     9  you need help.
    10  
    11  Gerrit assigns the following roles to users:
    12  
    13  * **Submitters**: May submit changes for consideration, review other code
    14    changes, and make recommendations for acceptance or rejection by voting
    15    +1 or -1, respectively.
    16  * **Maintainers**: May approve or reject changes based upon feedback from
    17    reviewers voting +2 or -2, respectively.
    18  * **Builders**: (e.g. Jenkins) May use the build automation infrastructure to
    19    verify the change.
    20  
    21  Maintainers should be familiar with the [review process](reviewing.md). However,
    22  anyone is welcome to (and encouraged!) review changes, and hence may find that
    23  document of value.
    24  
    25  ## Git-review
    26  
    27  There's a **very** useful tool for working with Gerrit called
    28  [git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This
    29  command-line tool can automate most of the ensuing sections for you. Of course,
    30  reading the information below is also highly recommended so that you understand
    31  what's going on behind the scenes.
    32  
    33  ## Sandbox project
    34  
    35  We have created a [sandbox
    36  project](https://gerrit.hyperledger.org/r/#/admin/projects/lf-sandbox) to allow
    37  developers to familiarize themselves with Gerrit and our workflows. Please do
    38  feel free to use this project to experiment with the commands and tools, below.
    39  
    40  ## Getting deeper into Gerrit
    41  
    42  A comprehensive walk-through of Gerrit is beyond the scope of this document.
    43  There are plenty of resources available on the Internet. A good summary can be
    44  found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial). We have also
    45  provided a set of [Best Practices](best-practices.md) that you may find helpful.
    46  
    47  ## Working with a local clone of the repository
    48  
    49  To work on something, whether a new feature or a bugfix:
    50  
    51  1. Open the Gerrit [Projects page](https://gerrit.hyperledger.org/r/#/admin/projects/)
    52  
    53  2. Select the project you wish to work on.
    54  
    55  3. Open a terminal window and clone the project locally using the `Clone with git
    56  hook` URL. Be sure that `ssh` is also selected, as this will make authentication
    57  much simpler:
    58  ```
    59  git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/
    60  ```
    61  
    62  **Note:** if you are cloning the fabric project repository, you will want to
    63  clone it to the `$GOPATH/src/github.com/hyperledger` directory so that it will
    64  build, and so that you can use it with the Vagrant [development
    65  environment](../dev-setup/devenv.md).
    66  
    67  4. Create a descriptively-named branch off of your cloned repository
    68  
    69  ```
    70  cd fabric
    71  git checkout -b issue-nnnn
    72  ```
    73  
    74  5. Commit your code. For an in-depth discussion of creating an effective commit,
    75  please read [this document](changes.md).
    76  
    77  ```
    78  git commit -s -a
    79  ```
    80  
    81  Then input precise and readable commit msg and submit.
    82  
    83  6. Any code changes that affect documentation should be accompanied by
    84  corresponding changes (or additions) to the documentation and tests. This
    85  will ensure that if the merged PR is reversed, all traces of the change will
    86  be reversed as well.
    87  
    88  ## Submitting a Change
    89  
    90  Currently, Gerrit is the only method to submit a change for review. **Please review
    91  the [guidelines](changes.md) for making and submitting a change**.
    92  
    93  ### Use git review
    94  
    95  **Note:** if you prefer, you can use the [git-review](#git-review) tool instead
    96  of the following. e.g.
    97  
    98  Add the following section to `.git/config`, and replace `<USERNAME>` with your 
    99  gerrit id.
   100  
   101  ```
   102  [remote "gerrit"]
   103      url = ssh://<USERNAME>@gerrit.hyperledger.org:29418/fabric.git
   104      fetch = +refs/heads/*:refs/remotes/gerrit/*
   105  ```
   106  
   107  Then submit your change with `git review`.
   108  
   109  ```
   110  $ cd <your code dir>
   111  $ git review
   112  ```
   113  
   114  When you update your patch, you can commit with `git commit --amend`, and then 
   115  repeat the `git review` command.
   116  
   117  ### Not Use git review
   118  
   119  Directions for building the source code can be found [here](../dev-setup/build.md).
   120  
   121  When a change is ready for submission, Gerrit requires that the
   122  change be pushed to a special branch. The name of this special branch
   123  contains a reference to the final branch where the code should reside,
   124  once accepted.
   125  
   126  For the Hyperledger Fabric Project, the special branch is called `refs/for/master`.
   127  
   128  To push the current local development branch to the gerrit server, open a
   129  terminal window at the root of your cloned repository:
   130  
   131  ```
   132  cd <your clone dir>
   133  git push origin HEAD:refs/for/master
   134  ```
   135  If the command executes correctly, the output should look similar to this:
   136  
   137  ```
   138  Counting objects: 3, done.
   139  Writing objects: 100% (3/3), 306 bytes | 0 bytes/s, done.
   140  Total 3 (delta 0), reused 0 (delta 0)
   141  remote: Processing changes: new: 1, refs: 1, done
   142  remote:
   143  remote: New Changes:
   144  remote:   https://gerrit.hyperledger.org/r/6 Test commit
   145  remote:
   146  To ssh://LFID@gerrit.hyperledger.org:29418/fabric
   147  * [new branch]      HEAD -> refs/for/master
   148  ```
   149  
   150  The gerrit server generates a link where the change can be tracked.
   151  
   152  ## Adding reviewers
   153  
   154  Optionally, you can add reviewers to your change.
   155  
   156  To specify a list of reviewers via the command line, add
   157  `%r=reviewer@project.org` to your push command. For example:
   158  
   159  ```
   160  git push origin HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com
   161  ```
   162     Alternatively, you can auto-configure GIT to add a set of reviewers if your
   163     commits will have the same reviewers all at the time.
   164  
   165     To add a list of default reviewers, open the :file:`.git/config` file in the
   166     project directory and add the following line in the `[ branch “master” ]`
   167     section:
   168  
   169  ```
   170  [branch "master"] #.... push =
   171  HEAD:refs/for/master%r=rev1@email.com,r=rev2@notemail.com`
   172  ```
   173  
   174  Make sure to use actual email addresses instead of the `@email.com and @notemail.com`
   175  addressses. Don't forget to replace `origin` with your git remote name.
   176  
   177  ## Reviewing Using Gerrit
   178  
   179  * **Add**: This button allows the change submitter to manually add names of
   180    people who should review a change; start typing a name and the system
   181    will auto-complete based on the list of people registered and with
   182    access to the system. They will be notified by email that you are
   183    requesting their input.
   184  
   185  * **Abandon**: This button is available to the submitter only; it allows a
   186    committer to abandon a change and remove it from the merge queue.
   187  
   188  * **Change-ID**: This ID is generated by Gerrit (or system). It becomes
   189    useful when the review process determines that your commit(s) have to
   190    be amended. You may submit a new version; and if the same Change-ID
   191    header (and value) are present, Gerrit will remember it and present
   192    it as another version of the same change.
   193  
   194  * **Status**: Currently, the example change is in review status, as indicated
   195    by “Needs Verified” in the upper-left corner. The list of
   196    Reviewers will all emit their opinion, voting +1 if they agree to the
   197    merge, -1 if they disagree. Gerrit users with a Maintainer role can
   198    agree to the merge or refuse it by voting +2 or -2 respectively.
   199  
   200  Notifications are sent to the email address in your commit message's
   201  Signed-off-by line. Visit your [Gerrit dashboard](https://gerrit.hyperledger.org/r/#/dashboard/self), to check the progress of your requests.
   202  
   203  The history tab in Gerrit will show you the in-line comments and the author of
   204  the review.
   205  
   206  ## Viewing Pending Changes
   207  
   208  Find all pending changes by clicking on the `All --> Changes` link in the
   209  upper-left corner, or [open this link](https://gerrit.hyperledger.org/r/#/q/project:fabric).
   210  
   211  If you collaborate in multiple projects, you may wish to limit searching to
   212  the specific branch through the search bar in the upper-right side.
   213  
   214  Add the filter *project:fabric* to limit the visible changes to
   215  only those from the Hyperledger Fabric Project.
   216  
   217  List all current changes you submitted, or list just those changes in need
   218  of your input by clicking on `My --> Changes` or [open this link](https://gerrit.hyperledger.org/r/#/dashboard/self)