post-review¶

Overview¶

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.

Installation¶

post-review is part of the RBTools package.

Before installing RBTools, you will need to have both Python and Setuptools installed.

We require Python 2.x. We recommend installing Python 2.7. The 3.x releases will not work.

Installing Python¶

Linux¶

Python 2.x should come with your distribution. If not, or if 2.x isn’t installed, you will need to install the appropriate package. Please refer to your package manager for the appropriate version.

Windows¶

You can install Python by running the latest Python 2.7 Installer for Windows. We recommend the 32-bit MSI installer, as Setuptools is not packaged for 64-bit.

Installing Setuptools¶

Linux¶

To install Setuptools on Debian, Ubuntu, or another Debian-based distribution, type:

$ apt-get install python-setuptools

To install on Fedora 8 and above, type:

$ yum install -y python-setuptools-devel.noarch

To install on a RedHat Enterprise, CentOS, Fedora 7 and earlier, or another RedHat-based distribution, type:

$ yum install python-setuptools

Users of other distributions should check with their distribution for native packages, or follow the setuptools installation instructions.

If the version of setuptools available for your distribution is older than 0.6c9, you’ll need to install it first, and then upgrade it to the latest version by running:

$ easy_install -U setuptools

Windows¶

You’ll then need to run the latest Python Setuptools Installer (look toward the bottom of the page for the file listing).

Once Python and Setuptools are installed, you may need to add a couple directories to your system path.

Open Start ‣ Control Panel and navigate to the System icon.
Click on the Advanced tab.
Click Environment Variables.
Find PATH in System variables and click Edit.
Add ;C:\Python27;C:\Python27\Scripts (substitute your Python directory if it’s not C:\Python27) to the end of the list.

Installing RBTools¶

Once Python and Setuptools are installed, you can install RBTools just by typing:

$ easy_install -U RBTools

Posting and Updating Review Requests¶

Depending on the repository type, 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 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, post-review will display the URL of the review request. If the -o parameter is passed, a browser will be opened to that URL.

The following subsections will explain how 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.

post-review must be used if you’re using Perforce with Review Board, as the diff generated by 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, 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 -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

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 post-review‘s parent diff support.

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 post-review to generate a parent diff between master and topicA.

This is done by using the --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¶

post-review provides basic support for posting ClearCase reviews. If you want to post a review of all currently checked out files in your view simply run:

post-review

If you collect changesets, for example, using ClearCase/ClearQuest integration, you can pass the changeset using --revision-range. Repository will be determined based on your current VOB’s uuid or name:

$ post-review --revision-range="/vobs/proj/file.c@@/main/0:/vobs/proj/file.c@@/main/1"

Another way for post-commit review is send changes developed on branch by --tracking option:

$ post-review --tracking my_dev_branch

Note

post-review trying match reviewboard’s repository based on VOB’s UUID. In case of problems Your VOB’s name will be used. Remember. You can always overwrite this behavior using .reviewboardrc `file or passing :option:–repository-url`.

Posting Committed Code¶

By default, post-review assumes that you’re posting uncommitted code. This is called a 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 post-commit review.

In order to do this, you can use the --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 -r parameter, as shown above.

Posting Existing Diffs¶

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 --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¶

It’s possible to automate post-review on a user’s behalf. This can be useful from a repository’s post-commit hook to automatically create or update a review request. This works through a combination of a special Review Board user and the --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 “Can submit as user” Permission and “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 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 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 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 /trunk or /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¶

The .reviewboardrc file is a generic place for configuring a repository. This must be in a directory in the user’s checkout path to work. It must parse as a valid Python file, or you’ll see an error when using post-review.

REPOSITORY¶

Normally, the repository path is automatically determined and passed to Review Board, but on more complex setups you may need to tell post-review and Review Board specifically which repository you want to use.

You can use the REPOSITORY setting to specify the path or the numeric ID of the repository to use. For example:

REPOSITORY = 'https://svn.example.com/'

If using Review Board 1.5.3 or higher, you can also choose to specify the repository name. This is the same name as on Review Board’s New Review Request page. For example:

REPOSITORY = 'RBTools'

REVIEWBOARD_URL¶

To specify the Review Board server to use, you can use the REVIEWBOARD_URL setting. This takes the URL to the Review Board server as a value. For example:

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

Custom User Configuration¶

If the repository isn’t configured for post-review and a custom script isn’t provided, you can create a .reviewboardrc file in your HOME directory (usually /home/username on Linux, $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¶

-d, --debug¶: Displays detailed debug output in the terminal.

-h, --help¶: Shows the help for the program and exits.

-o, --open¶: Opens a web browser to the address of the review request.

--version¶: Shows the version number and exits.

Server Options¶

--server=<URL>¶: Specifies the URL of Review Board server to use. By default, post-review will try to scan for the correct repository.

--submit-as=<USERNAME>¶

Specifies the username to use for any updated made to the review request. This is different than --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 Automating post-review for usage information.

--username=<USERNAME>¶: Specifies the username used to log in to the Review Board server. If not specified, post-review will prompt for it.

--password=<PASSWORD>¶: Specifies the password used to log in to the Review Board server. If not specified, post-review will prompt for it.

Review Request Options¶

-p, --publish¶: Publishes the review request immediately after submitting. Normally the change is left as a draft.

-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.

--revision-range=<REVISION_RANGE>¶: Specifies a revision or a range of revisions used to generate the diff. See Posting Committed Code for usage information.

Field Defaults Options¶

--branch=<BRANCH>¶: Sets the review request’s branch field to the specified text.

--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.

--description=<DESCRIPTION>¶: Sets the description for the review request to the specified text.

--description-file=<FILENAME>¶: Sets the description for the review request to the contents of the specified file.

--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 Posting Existing Diffs for usage information.

--summary=<SUMMARY>¶: Sets the review request’s summary field to the specified text.

--target-groups=<TARGET_GROUPS>¶: Provides a list of groups that should be on the reviewer list. This should be a comma-separated list.

--target-people=<TARGET_PEOPLE>¶: Provides a list of usernames that should be on the reviewer list. This should be a comma-separated list.

--testing-done=<TESTING_DONE>¶: Sets the testing done text for the review request to the specified text.

--testing-done-file=<FILENAME>¶: Sets the testing done text for the review request to the contents of the specified file.

ClearCase Options¶

--label=<LABEL>¶: Specifies the label used for ClearCase.

Git Options¶

--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 --description.

--guess-summary¶

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

This cannot be used with --summary.

Git and Mercurial Options¶

--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 Distributed Version Control Systems for usage information.

Perforce Options¶

--change-only¶: Updates the review request information (description, testing done, etc.) based on the change number provided, but doesn’t update the diff.

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

--p4-client=<P4_CLIENT>¶: Specifies the Perforce client name that should be used when generating the diff.

--p4-port=<P4_PORT>¶: Specifies the Perforce server IP address used when generating the diff.

--p4-passwd=<PASSWORD_OR_TICKET>¶: Specifies the Perforce Ticket or clear-text password used to authenticate with the repository.

Subversion Options¶

--repository-url=<URL>¶: Specifies the Subversion repository URL used when generating the diff. This only works in conjunction with --revision-range.