.. _post-review:
.. program:: post-review

===========
post-review
===========

Overview
============

:command:`post-review` is a command line tool for Windows, Linux and MacOS X
that simplifies both creating and updating review requests. It can look at
your source directory, generate a diff, and upload it to a new or existing
review request on an associated Review Board server. This saves a lot of time
over the web UI, and for some types of code repositories (such as Perforce),
it's actually required in order to produce a compatible diff.

:command:`post-review` is part of the RBTools package, and can be installed
and upgraded by running::

    $ easy_install -U RBTools


Posting and Updating Review Requests
====================================

Depending on the repository type, :command:`post-review` will either require
a changeset number, or it will rely on the changes in the current source
tree. The end result is that :command:`post-review` will build a diff and
post it to a Review Board server. The diff and any additional review
request information will be saved on the server as a draft, which can then
be published.

After posting a new review request or updating an existing one,
:command:`post-review` will display the URL of the review request.
If the :option:`-o` parameter is passed, a browser will be opened to
that URL.

The following subsections will explain how :command:`post-review` is used
with different repository types.


Perforce
--------

Posting Changesets
~~~~~~~~~~~~~~~~~~

Perforce has a concept of changesets, which are server-stored descriptions of
a change along with an ID number and associated files. For Perforce, Review
Board stores changeset numbers of a posted change and can use these to
associate particular changes with review requests.

To post a review request for a specific change, or to update an existing
review request for that change, type::

    $ post-review CHANGENUM

Where ``CHANGENUM`` is the changeset number in Perforce.

The diff will be generated and uploaded to Review Board, and the review
request information will be updated based on the changeset description.

:command:`post-review` must be used if you're using Perforce with
Review Board, as the diff generated by :command:`p4 diff` doesn't provide
the information necessary to properly display a side-by-side diff.


Posting Paths
~~~~~~~~~~~~~

There are cases where you may want to post individual paths containing files
instead of changesets. Take the following cases, for example:

* You have code or other files that must be checked in before they're
  reviewed and have undergone multiple changes.
* You're working in a side branch for a while, possibly with other people,
  and need to review the code before it's integrated into the main branch.
* You want to post a really old, previously abandoned change for review
  that previously went unreviewed.

To post with a path, :command:`post-review` should be run with a standard
Perforce depot path as a parameter, which may contain revision information.
The following paths are supported:


**Uploading a file as a "new" file**::

   //path/to/file

**Uploading all files in a directory as "new" files**::

   //path/to/dir/...

**Uploading a file from a revision as a "new" file (not as common)**::

   //path/to/file/[@#]rev

**Uploading a diff of a file between two revisions**::

   //path/to/file[@#]rev,[@#]rev

**Uploading a diff of all files between two revisions in a directory**::

   //path/to/dir/...[#@]rev,[#@]rev


CVS and Subversion
------------------

CVS and Subversion don't have a concept of changesets, so instead the
working copy's uncommitted changes are posted for review. To post a
review request with all uncommitted files in a tree, simply run::

    $ post-review

This will create a new review request and post the diff of the uncommitted
changes. If you instead want to update an existing review request with
new changes, use the :option:`-r` parameter. For example, to update
review request #42, type::

    $ post-review -r 42

If you need to post specific files, leaving other uncommitted files out of
the review request, you can include them on the command line, like so::

    $ post-review src/foo.c data/bar.png


.. _DVCS:

Distributed Version Control Systems
-----------------------------------

If you're using a distributed version control system, such as Git or
Mercurial, then you may be working on code based on a branch that isn't
available to the repository Review Board has configured. In these cases,
you'll want to take advantage of :command:`post-review`'s parent diff
support.

.. index:: parent diffs

A parent diff is a diff between some known upstream revision that Review Board
has access to and the parent of your branch. It's used to provide a working
baseline for your branch's diff.

For example, in the case of Git, you may be working on the ``topicB`` branch,
which has an ancestry that looks like::

   o master
    \
     o---o topicA
          \
           o---o topicB

If you want to upload a diff of everything between ``topicA`` and ``topicB``,
you would need to tell :command:`post-review` to generate a parent diff
between ``master`` and ``topicA``.

This is done by using the :option:`--parent` parameter with the branch name.
For example, in this case you would simply do::

    $ post-review --parent=topicA

That would generate a parent diff between ``master`` and ``topicA``, and
a normal diff of your changes between ``topicA`` and ``topicB``. The changes
in the parent diff won't appear as changed lines in the diff viewer, meaning
that users will only see changes made on ``topicB``.

.. note:: This only works with Git right now, and makes an assumption that
          ``master`` represents an upstream revision that Review Board has
          access to. Normally this means that ``master`` and ``origin`` should
          point to the same revision. In the future, this will be more
          flexible.

ClearCase
---------

:command:`post-review` provides basic support for posting ClearCase reviews,
but requires some initial setup to be used. Edit the :attr:`cc_rootpath`
variable in the :class:`ClearcaseClient` class to point to a view from which
you want to create a review request. Change the :attr:`viewtype` variable::

    viewtype = "dynamic"

.. note:: Snapshot views are not currently supported.

To post the review request, you must pass a list of modified files to
:command:`post-review`. If you want to post a review of all checked out files
in your view, you can do this with the following command line in a suitable
shell::

    $ cleartool lsco -cview -me -recurse -short | xargs post-review

On Windows, you'll need to fix the paths to contain forward-slashes::

    $ cleartool lsco -cview -me -recurse -short | sed "s/\\\\/\//g" | xargs post-review

.. note:: Only uncommited code reviews are currently supported.


.. index:: post-commit review
.. _postingcommittedcode:

Posting Committed Code
======================

By default, :command:`post-review` assumes that you're posting uncommitted
code. This is called a :term:`pre-commit review`. However, it's sometimes
useful to post code that has already been committed to a repository, such
as in an experimental branch. This is a :term:`post-commit review`.

In order to do this, you can use the :option:`--revision-range` parameter,
which will generate a diff based on a range of committed revisions.
This allows a single review request to show a diff representing the entire
history of a branch, if desired.

Usage is easy. Simply type::

    $ post-review --revision-range=STARTREV:STOPREV

Where ``STARTREV`` is the beginning revision in the range, and
``STOPREV`` is the ending revision, inclusive. If you only need to post
a single revision, you can type::

    $ post-review --revision-range=REVISION

In order to update an existing review request, you can use the
:option:`-r` parameter, as shown above.


.. _postingexistingdiffs:

Posting Existing Diffs
======================

:command:`post-review` will generate diffs automatically based on the
repository type, but if you need to post a pre-existing diff, you can
use the :option:`--diff-filename` parameter to specify the path to
the diff file.

For example::

    $ post-review --diff-filename=mycode.diff

You can also use the special value of ``-`` to pipe a diff into STDIN::

    $ cat mycode.diff | post-review --diff-filename=-


.. _automating-post-review:

Automating post-review
======================

It's possible to automate :command:`post-review` on a user's behalf. This can
be useful from a repository's :term:`post-commit hook` to automatically
create or update a review request. This works through a combination of a
special Review Board user and the :option:`--submit-as` option.

To set this up, first register a new user. This user will be specific to
your script, and will have special permissions, so make sure the password
is protected. You'll then want to grant the
:ref:`can-submit-as-user-permission` and
:ref:`can-edit-review-request-permission` to the user. This will give this
user to the ability to modify a review request as another user.

You can then invoke :command:`post-review` by doing the following::

    $ post-review --username=SPECIAL_USER --password=PASSWORD --submit-as=ANOTHER_USER

Of course, you can pass any other values as you see fit.

This will log in as ``SPECIAL_USER`` and perform operations as
``ANOTHER_USER``.


Configuration
=============

There are many ways to configure :command:`post-review` in order to associate
a Review Board server with a repository. The ideal setup is to configure
a repository to point to a Review Board server, so that users can use
:command:`post-review` out of the box, but there are other methods available.


Repository Configuration
------------------------

Some repository types can have special metadata associated to point to a
server. All repository types support per-directory dot files.


Git Properties
~~~~~~~~~~~~~~

Repository information can be set in a ``reviewboard.url`` property on
the Git tree. Users may need to do this themselves on their own Git
tree, so in some cases, it may be ideal to use dotfiles instead.

To set the property on a Git tree, type::

    $ git config reviewboard.url http://reviewboard.example.com


Perforce Counters
~~~~~~~~~~~~~~~~~

Repository information can be set on Perforce servers by using
``reviewboard.url`` Perforce counters. How this works varies between versions
of Perforce.

Perforce version 2008.1 and up support strings in counters, so you can simply
do::

    $ p4 counter reviewboard.url http://reviewboard.example.com

Older versions of Perforce support only numeric counters, so you must encode
the server as part of the counter name. As ``/`` characters aren't supported
in counter names, they must be replaced by ``|`` characters. ``|`` is a
special character in shells, so you'll need need to escape these using ``\|``.
For example::

    $ p4 counter reviewboard.url.http:\|\|reviewboard.example.com 1


Subversion Properties
~~~~~~~~~~~~~~~~~~~~~

Repository information can be set in a ``reviewboard:url`` property on
a directory. This is usually done on whatever directory or directories
are common as base checkout paths. This usually means something like
:file:`/trunk` or :file:`/trunk/myproject`. If the directory is in the
user's checkout, it will be faster to find the property.

To set the property on a directory, type::

    $ svn propset reviewboard:url http://reviewboard.example.com .


.reviewboardrc
~~~~~~~~~~~~~~

You can set the repository URL in :file:`.reviewboardrc` file in any
directory. This must be a directory in the user's checkout path to work.

The contents of the file should be::

    REVIEWBOARD_URL = "http://reviewboard.example.com"


Internal post-review Configuration
----------------------------------

:command:`post-review` itself can be modified with the path of the
repository. This is useful in companies where there's only one Review
Board server and the other methods aren't acceptable.

You can edit :command:`post-review` and look for the line::

    REVIEWBOARD_URL = None

And replace this with the server path, such as::

    REVIEWBOARD_URL = "http://reviewboard.example.com"

There are also other more advanced customization options available for
specialized cases. See the documentation and variables inside
:command:`post-review` for more information.

.. warning:: If you customize this file, it may make it harder to upgrade
             to newer versions of :command:`post-review` in the future.
             It's advised that you use a custom copy of the script and
             not one that was installed by a package, or your changes
             *will* get overridden.


Custom User Configuration
-------------------------

If the repository isn't configured for :command:`post-review` and a
custom script isn't provided, you can create a :file:`.reviewboardrc`
file in your HOME directory (usually :file:`/home/{username}` on Linux,
:file:`$USERPROFILE\\Local Settings\\Application Data` on Windows).

In the simplest case with only one Review Board server you'll ever
interact with, the file can simply contain::

    REVIEWBOARD_URL = "http://reviewboard.example.com"


A more complex setup for servers based on repository paths will look
more like::

    TREES = {
        'http://svn.example.com': {
            'REVIEWBOARD_URL': 'http://reviewboard.example.com',
        },
        'username@cvs.example.com:/cvsroot/cvs': {
            'REVIEWBOARD_URL': 'http://reviewboard.example.com',
        },
    }


Any number of repository paths can be specified. The repository path
must match a repository configured in the Review Board server.


Options
=======

Basic Options
-------------

.. cmdoption:: -d, --debug

   Displays detailed debug output in the terminal.

.. cmdoption:: -h, --help

   Shows the help for the program and exits.

.. cmdoption:: -o, --open

   Opens a web browser to the address of the review request.

.. cmdoption:: --version

   Shows the version number and exits.


Server Options
--------------

.. cmdoption:: --server=<URL>

   Specifies the URL of Review Board server to use. By default,
   :command:`post-review` will try to scan for the correct repository.

.. cmdoption:: --submit-as=<USERNAME>

   Specifies the username to use for any updated made to the review request.
   This is different than :option:`--username` in that this username is not
   used for logging in to the server. A login user with necessary
   permissions must be used in order for this parameter to work.

   This is useful when used in a repository's post-commit script to update
   a review request. See :ref:`Automating post-review` for usage information.

.. cmdoption:: --username=<USERNAME>

   Specifies the username used to log in to the Review Board server. If not
   specified, :command:`post-review` will prompt for it.

.. cmdoption:: --password=<PASSWORD>

   Specifies the password used to log in to the Review Board server. If not
   specified, :command:`post-review` will prompt for it.


Review Request Options
----------------------

.. cmdoption:: -p, --publish

   Publishes the review request immediately after submitting. Normally
   the change is left as a draft.

.. cmdoption:: -r=<ID>, --review-request-id=<ID>

   Updates an existing review request, instead of creating a new one. The
   ``ID`` is the review request number to use.

.. cmdoption:: --revision-range=<REVISION_RANGE>

   Specifies a revision or a range of revisions used to generate the diff.
   See :ref:`Posting Committed Code` for usage information.


Field Defaults Options
----------------------

.. cmdoption:: --branch=<BRANCH>

   Sets the review request's branch field to the specified text.

.. cmdoption:: --bugs-closed=<BUGS_CLOSED>

   Specifies a list of bug numbers to use for the Bugs Closed section
   in the review request. This should be a comma-separated list.

.. cmdoption:: --description=<DESCRIPTION>

   Sets the description for the review request to the specified text.

.. cmdoption:: --description-file=<FILENAME>

   Sets the description for the review request to the contents of the
   specified file.

.. cmdoption:: --diff-filename=<FILENAME>

   Specifies an existing diff file to upload, instead of generating a new
   diff. The special value of ``-`` allows the diff to be piped into
   STDIN. See :ref:`Posting Existing Diffs` for usage information.

.. cmdoption:: --summary=<SUMMARY>

   Sets the review request's summary field to the specified text.

.. cmdoption:: --target-groups=<TARGET_GROUPS>

   Provides a list of groups that should be on the reviewer list. This
   should be a comma-separated list.

.. cmdoption:: --target-people=<TARGET_PEOPLE>

   Provides a list of usernames that should be on the reviewer list. This
   should be a comma-separated list.

.. cmdoption:: --testing-done=<TESTING_DONE>

   Sets the testing done text for the review request to the specified text.

.. cmdoption:: --testing-done-file=<FILENAME>

   Sets the testing done text for the review request to the contents of the
   specified file.


ClearCase Options
-----------------

.. cmdoption:: --label=<LABEL>

   Specifies the label used for ClearCase.


Git Options
-----------

.. cmdoption:: --guess-description

   Sets the description of the review request based on all the commit
   messages between the parent branch and HEAD.

   This cannot be used with :option:`--description`.

.. cmdoption:: --guess-summary

   Sets the summary of the review request based on the commit message of
   the most recent commit.

   This cannot be used with :option:`--summary`.


Git and Mercurial Options
-------------------------

.. cmdoption:: --parent=<PARENT_BRANCH>

   Specifies a parent branch that the diff should be based upon. This is
   useful when working on a branch based on another uncommitted branch.

   See :ref:`DVCS` for usage information.


Perforce Options
----------------

.. cmdoption:: --change-only

   Updates the review request information (description, testing done, etc.)
   based on the change number provided, but doesn't update the diff.

.. cmdoption:: --diff-only

   Uploads the new diff, but doesn't modify the review request information
   (description, testing done, etc.) based on the change number provided.

.. cmdoption:: --p4-client=<P4_CLIENT>

   Specifies the Perforce client name that should be used when generating
   the diff.

.. cmdoption:: --p4-port=<P4_PORT>

   Specifies the Perforce server IP address used when generating the diff.


Subversion Options
------------------

.. cmdoption:: --repository-url=<URL>

   Specifies the Subversion repository URL used when generating the diff.
   This only works in conjunction with :option:`--revision-range`.


.. comment: vim: ft=rst et ts=3
