github.com/wallyworld/juju@v0.0.0-20161013125918-6cf1bc9d917a/doc/contributions/reviewboard.md (about)

     1  juju and Code Review
     2  ====================
     3  
     4  The `juju` project uses ReviewBoard for code review, falling back to
     5  github in the event that ReviewBoard is not available.  The review site
     6  is found at:
     7  
     8   http://reviews.vapour.ws/
     9  
    10  Authentication
    11  --------------
    12  
    13  The site uses github OAuth for authentication.  To log in simply go to
    14  login page and click the "github" button.  The first time you do this,
    15  it will redirect you to github to approve access and then redirect you
    16  back.  This first time is the only one where you will be redirected to
    17  github.  Furthermore, ReviewBoard will keep you logged in between visits
    18  via session cookies.
    19  
    20  That first time you log in, a ReviewBoard account will be created for
    21  you using your github username.  However, no other account information
    22  (including email address) is added for you.
    23  
    24  All OAuth login capability is provided by a ReviewBoard plugin (via a
    25  charm):
    26  
    27   https://pypi.python.org/pypi?name=rb_oauth&:action=display
    28  
    29  Email Notifications
    30  -------------------
    31  
    32  As noted, your email address is not automatically added to your
    33  reviewboard account.  If you want to receive review-related email, be
    34  sure to add your email address to your ReviewBoard profile.
    35  
    36  Github Integration
    37  ------------------
    38  
    39  We have webhooks set up on our Github repos that trigger on pull request
    40  events.  The webhooks send the pull request data to the ReviewBoard site
    41  which does the following for new pull requests:
    42  
    43  1. create a new review request for the PR
    44  2. add a link to the PR on the review request 
    45  3. add a link to the review request on the PR body
    46  
    47  When a pull request is updated, the review request is updated with the
    48  latest diff.  When a PR is closed, the corresponding review request is
    49  closed.  Likewise if a PR is re-opened.
    50  
    51  The Github integration means that for normal review workflow, the only
    52  required tool is our ReviewBoard site.
    53  
    54  All ReviewBoard-Github integration is provided by a ReviewBoard plugin
    55  (without a charm):
    56  
    57   https://bitbucket.org/ericsnowcurrently/rb_webhooks_extension
    58  
    59  
    60  Manual Review Workflow
    61  ======================
    62  
    63  In cases where the github-reviewboard integration does not work, some or
    64  all of these manual steps will be necessary for review workflow.
    65  
    66  Requirements
    67  ------------
    68  
    69  Some manual workflow steps require the `rbt` commandline tool.  More
    70  details on installation and usage are found below.
    71  
    72  .reviewboardrc
    73  --------------
    74  
    75  `rbt` requires a .reviewboardrc file at the top of the repo on which you
    76  are working.  Some of the juju repos have this file committed.  For
    77  those that do not, you will need to run `rbt setup-repo` to generate
    78  one.  Alternately copy the same file from a repo that has it and update
    79  "REPOSITORY" to the label for the current repo in ReviewBoard.  In
    80  either case, the file should also be committed and merged upstream.
    81  This has already been done for at least some of the key repos.
    82  
    83  If you followed the recommendation from CONTRIBUTING.md on git "remotes"
    84  (which you should have), you will need to make sure you have the
    85  following in the .reviewboardrc file:
    86  
    87   TRACKING_BRANCH = "upstream/master"
    88  
    89  Otherwise rbt will generate incorrect diffs.
    90  
    91  Manually Creating New Review Requests
    92  -------------------------------------
    93  
    94  Once you have logged in to ReviewBoard for the first time you are ready
    95  to create new review requests.  Each review request should be associated
    96  with a pull request on github.  So after your pull request is created,
    97  follow these steps:
    98  
    99  1. run "rbt post" (see more info below on RBTools)
   100  2. follow the link and hit the "publish" button (or use the "-p" option)
   101  3. add a comment to the PR with a link to the review request
   102  
   103  At this point your review request should get reviewed.  Make sure to
   104  address the feedback.  Your request might go through several rounds of
   105  feedback before the patch is approved or rejected.
   106  
   107  Manually Updating an Existing Review Request
   108  --------------------------------------------
   109  
   110  To update an existing pull request:
   111  
   112  1. push your updated branch to your github clone (this will
   113     automatically update the pull request)
   114  2. run "rbt post -u" or "rbt post -r #"
   115  3. hit the "publish" button (or use the "-p" option)
   116  
   117  Important: Make sure you use one of those two options.  Otherwise there
   118  is a good chance that ReviewBoard will create a new review request,
   119  which is a problem because revisions are linked to review requests
   120  (even discarded ones).  So the accidental review request would prevent
   121  you from updating the correct one after that.  If that happens you will
   122  need to get one of the ReviewBoard admins to delete the accidental
   123  review request.  Considering the overhead involved for everyone, it
   124  would be better just make sure you always use "-u" or "-r" for updates.
   125  
   126  
   127  ReviewBoard
   128  ===========
   129  
   130  ReviewBoard is an open-source code review tool that provides a full-
   131  featured web interface, an extensive remote API, and a command-line
   132  client.  Furthermore, it is easy to install and highly extensible
   133  through a plugin framework.
   134  
   135  For more information see https://www.reviewboard.org/docs/.
   136  
   137  RBTools (rbt)
   138  -----------------------------
   139  
   140  `rbt` is the command-line client to the ReviewBoard remote API.  You
   141  will need to install it before you can use it.  The documentation for
   142  the tools provides instructions.
   143  
   144    https://www.reviewboard.org/docs/rbtools/0.6/
   145  
   146  While `rbt` provides different functionality through various
   147  subcommands, the main case is creating and updating review requests.
   148  This is done via `rbt post`.
   149  
   150  The rbtools documentation includes information on various helpful
   151  command-line options.  These include:
   152  
   153  * automatically publish the draft request/update: rbt post -p
   154  * automatically open the request in your browser: rbt post -o
   155  
   156  For best results when using `rbt`:
   157  
   158  * make sure you are on the branch that matches the PR for which you are
   159    creating a review request
   160  * make sure that branch is based on an up-to-date master
   161  
   162  rbt Authentication
   163  ------------------
   164  
   165  The first time you use `rbt`, rbtools will request your ReviewBoard
   166  credentials.  Since our ReviewBoard users do not have passwords you must
   167  trigger OAuth authentication:
   168  
   169    username: `<github username>`
   170    password: `oauth:<github username>@github`
   171  
   172  Other Features
   173  --------------
   174  
   175  `rbt post --parent` allows you to chain review requests.