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.

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, 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, but requires some initial setup to be used. Edit the cc_rootpath variable in the ClearcaseClient class to point to a view from which you want to create a review request. Change the 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 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.

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¶

You can set the repository URL in .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¶

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 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 post-review for more information.

Warning

If you customize this file, it may make it harder to upgrade to newer versions of 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 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.

Subversion Options¶

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