Web Interface

The web interface of hg-review is probably what you’re going to use the most.

Running Locally

To start the web interface for a local repository that you want to review you can run hg review --web. Visit http://localhost:8080/ to use it.

When you add comments or signoffs hg-review will use your normal Mercurial username as the author.

This command can take a few extra options:

--address ADDRESS

The address to bind to. Use 0.0.0.0 if you want other people to be able to access it.

Be careful! Because the web interface uses your Mercurial username by default, binding to 0.0.0.0 will let anyone add comments and signoffs in your name! You’ll probably want to use the --read-only option to prevent this.

Default: 127.0.0.1

--port PORT

The port to listen on.

Default: 8080

--read-only

Run the server in read-only mode. This will not allow data to be pushed or pulled, comments to be made or signoffs to be added.

This can be useful when combined with --address to let other people view the UI without letting them add comments in your name.

Default: false

--allow-anon

Allow comments (not not signoffs) to be added even if --read-only is used, and set the username to Anonymous <anonymous@example.com> instead of your Mercurial username.

This option is most useful when you’re deploying a permanent web interface to a server and want to allow anonymous viewers to add comments. See the Deployment to a Server section for more information.

Default: false

Deployment to a Server

Although hg-review is built for distributed code review it’s sometimes nice to provide a public interface. This will let people can comment easily without using the extension (or even cloning your project).

Initial Deployment

You can use any WSGI server you like to provide a public instance of hg-review. Before you start you’ll need to have Mercurial installed on your web server.

Once you’ve got Mercurial running on the server you’ll need to clone copies of hg-review, your project, and your project’s review data to the web server. First create a directory where everything will live:

mkdir /var/www/myproject-review-interface/
cd /var/www/myproject-review-interface/

Then grab a copy of hg-review:

hg clone http://bitbucket.org/sjl/hg-review/

Grab a copy of your project and configure it to use the hg-review extension as well as the built-in fetch extension (to automatically merge updates):

hg clone -U http://bitbucket.org/you/yourproject/
cd yourproject

echo '[extensions]' >> .hg/hgrc
echo 'review = /var/www/myproject-review-interface/hg-review/review' >> .hg/hgrc
echo 'fetch = ' >> .hg/hgrc

Use hg-review to pull down the review data:

hg review --init

Now that you’ve got all the necessary data you can set up the WSGI script. Start by copying the included sample script:

cd /var/www/myproject-review-interface/
cp hg-review/contrib/deploy/wsgi.py wsgi.py

Edit the script to configure your project to your liking. For reference, the relevant part of the script should look something like this:

# An example WSGI script for serving hg-review's web UI.
# Edit as necessary.

# If hg-review is not on your webserver's PYTHONPATH, uncomment the lines
# below and point it at the hg-review directory.
import sys
sys.path.insert(0, "/var/www/myproject-review-interface/hg-review")

REPO = '/var/www/myproject-review-interface/myproject'
READ_ONLY = True
ALLOW_ANON_COMMENTS = False
ANON_USER = 'Anonymous <anonymous@example.com>'
SITE_ROOT = 'http://yoursite.com/optional/path'
TITLE = 'Your Project'
PROJECT_URL = 'http://bitbucket.org/your/project/' # or None

All that’s left is to point your WSGI server at this script and fire it up. How you do that depends on your WSGI server. A sample configuration file for Gunicorn is provided in contrib/deploy/gunicorn.conf.py.

Updating the Data

You’ll want to keep the review data for this interface current so users can see all the latest comments and signoffs.

To do this you simply need to pull in the main repository (to receive new changesets in your project) and fetch in the review data repository (to receive new comments and signoffs):

hg -R /var/www/myproject-review-interface/ pull
hg -R /var/www/myproject-review-interface/.hg/review fetch

New comments and signoffs will be visible immediately – you don’t need to restart your WSGI server.

You’ll probably want to set this up as a cron job or use a hook of some kind to automate the updates.

If you allow anonymous comments and want people that are using the extension locally (instead of this public instance) to see these comments, you’ll need to fetch and push the review data repo as well:

hg -R /var/www/myproject-review-interface/.hg/review/ fetch
hg -R /var/www/myproject-review-interface/.hg/review/ push

hg-review is designed to never encounter merge conflicts with its data, but there’s always the chance that someone has done something manually that could cause a problem.

If your interface doesn’t seem to be receiving new comments/signoffs you’ll want to take a look at the review data repository to see what’s wrong:

cd /var/www/myproject-review-interface/.hg/review
hg heads

There should only ever be one head in this repository. If there are more you’ll need to merge them (and push back to your public review data repo so others won’t encounter the same problem).