docs/overview.rst @ a572f4405909

Overview
========

Let's get started using hg-review.  No matter how you want to use it, you need
to install it first. 

Installation
------------

hg-review requires `Python <http://python.org>`_ 2.5 or later and `Mercurial
<http://hg-scm.org>`_ 1.6 or later.

You probably have both of these requirements already, but if you encounter
problems you might want to check these first with ``python --version`` and
``hg --version``.

hg-review also depends on a couple of other things like `Flask
<http://flask.pocoo.org>`_ and `Jinja2 <http://jinja.pocoo.org/2/>`_, but it
bundles these requirements so you don't need to worry about them.

To install hg-review, first clone the extension somewhere::

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

Then add it to your ``~/.hgrc`` file::

    [extensions]
    review = [path to]/hg-review/review/

Usage
-----

The easiest way to work with hg-review is with the :doc:`web interface
</webui>`.  There's also a :doc:`command-line interface </cli>`, but it's
easiest to work with the web interface.

Projects with Existing Code Reviews
'''''''''''''''''''''''''''''''''''

If you want to work with a repository that already has code review set up all
you need to do is cd into that repository, pull down the review data, and fire
up the web ui::

    cd ~/src/someproject
    hg review --init
    hg review --web

Once that's done you can visit http://localhost:8080/ in your browser to start
reviewing.

You should read over the :doc:`concepts </concepts>` documentation to make sure
you know how hg-review works and the :doc:`web interface </webui>`
documentation for a quick tour of how to use the web UI.

Projects without Existing Code Reviews
''''''''''''''''''''''''''''''''''''''

If you want to *start* using hg-review with a repository, you need to do a few
things to get it ready. You'll want to end up with something like this:

.. image:: /_static/basic.png
   :alt: hg-review basic structure diagram
   :align: center

First, create a public repository to hold the code review data. This repository
should be in a location that's accessible by anyone that needs to see the
review data.

For example, if you're working on an open-source project that's hosted at
http://bitbucket.org/you/project/ you should create a new repository for
the review data at http://bitbucket.org/you/project-review/

Next you'll need to initialize the review data in your project. ``cd`` into you
project's directory and run:: 

    hg review --init --remote-path URL

The ``URL`` should be the *public* URL of the review repo you just created.

This command will create a *local* review data repo for you in ``.hg/review``,
as well as an ``.hgreview`` file in your project. You need to commit this
``.hgreview`` file to your project with the command that hg-review suggested.

Don't worry, this is the only time hg-review will make you commit something to
your project's repository and clutter up its changelog.

Now you can get to work reviewing changesets with the web interface by
running ``hg review --web`` in your project.

You should read over the :doc:`concepts </concepts>` documentation to make sure
you know how hg-review works, and the :doc:`web interface </webui>`
documentation for a quick tour of how to use the web UI.

Reporting Bugs
--------------

If you encounter any errors while using hg-review please `post a bug
<http://bitbucket.org/sjl/hg-review/issues/>`_.