docs/concepts.rst @ f82c3447cf49 initial-docs

Concepts
========

You're not perfect.

Your code is not perfect.

If you're the only person that's read your code, it's wrong. Period.

As developers we need to review each other's code. This helps us catch errors
before they find our users. It also makes us take greater care when writing
code because we know someone will most definitely be looking at it.

Code Review Basics
------------------

The simplest form of code review is asking a friend to look at the code you
just wrote. Often a second set of eyes can find problems you might not have
seen, especially if that person has more experience than you.

Unfortunately, this isn't always practical. You might work remotely with people
thousands of miles away and not have a chance to simply turn around and say:
"Hey, could you look at this?"

Code review tools (like hg-review) exist to make reviewing other people's code
easier.

Their goal is to make it as easy as possible to tell another developer: "No,
you did *this* wrong.  Fix it."

Other Code Review Tools
-----------------------

There are a lot of "code review tools" out there.

The primary author of hg-review has a lot of experience with `Atlassian
Crucible <http://www.atlassian.com/software/crucible/>`_, but some other
popular tools include:

* `Rietveld <http://codereview.appspot.com/>`_
* `Reviewboard <http://www.reviewboard.org/>`_
* `Gerrit <http://code.google.com/p/gerrit/>`_
* `Code Collaborator <http://smartbear.com/codecollab.php>`_

All of these tools try to accomplish the same goal: making it easy for
developers to tell each other how to write better code.

hg-review has the same goal, but it goes about it a little differently.

Distributed Code Review
-----------------------

Let's back up for just a second and talk about version control. Some of the
most popular version control systems a few years ago were *centralized* systems
like `Subversion <http://subversion.apache.org/>`_ and
`CVS <http://www.nongnu.org/cvs/>`_.

With these systems you had a central server that contained all the history of
your project. You would push changes to this central server and it would store
them.

In the past half-decade or so there has been a move toward *decentralized* or
*distrubuted* version control systems. With these systems you commit to your
local machine and then *push* and *pull* your commits to other people.

Code review tools, however, seem to have remained rooted in the "centralized
server" approach.  Even the tools that support decentralized version control
systems like `git <http://git-scm.com>`_ and `Mercurial <http://hg-scm.org>`_
rely on a central server to store the code review data.

hg-review does away with the "centralized data store" model and embraces
Mercurial's distributed nature. Code review data is held in a normal Mercurial
repository and can be pushed and pulled like any other type of data.

This has several advantages, the biggest one being that you can review code
while offline (while in a bus, plane, train or car, or example) without
sacrificing any functionality.

It also means that the full power of Mercurial, such as tracking history and
signing changesets with GPG, can be brought to bear on the review data.

Review Data
-----------

hg-review tracks two kinds of code review data: comments and signoffs.

Comments are simple comments that people make about changesets. People can
comment on:

* A changeset as a whole.
* A specific file within a changeset.
* One or more lines of a specific file within a changeset.

Signoffs, on the other hand, *always* apply to a changeset as a whole. Each
person can have on signoff for any particular changeset (though they can edit
their signoff later).

Signoffs can be used for whatever purpose your project might find useful, but
the author of hg-review recommends that they be used to mean:

    I approve of this changeset and think it should make its way to production.

for signoffs of "Yes" and: 

    I do not approve of this changeset and do not think it should make its way to
    production without another changeset on top of it that fixes the problems
    I have listed.

for signoffs of "No."

Signoffs of "neutral" might mean:

    This changeset doesn't really impact me, so I don't care.

or perhaps:

    I've looked at this code but don't have the expertise to provide a useful
    opinion.


Repository Structure
--------------------

While it's not necessary to know exactly how the guts of hg-review work, it
*is* helpful to understand the basic idea behind it.

Let's say you have a project with a Mercurial repository in
``~/src/yourproject/`` and you'd like to start using hg-review with it.

The first thing to understand is that Mercurial itself stores data about this
local repository in ``~/src/yourproject/.hg/``, and that data is local to your
machine. It is never committed or tracked by Mercurial, but is instead used by
the Mercurial program itself to work with your repository.

hg-review creates a *separate* Mercurial repository to keep track of its data.
It stores this repository in ``~/src/yourproject/.hg/review/``.

Because this is inside of Mercurial's internal ``.hg`` directory of your
project, changes to the review data (like comments and signoffs) won't be
tracked by your project's repository.

Instead, hg-review manages its own data in its own repository to avoid
cluttering up your project's log with useless "added a comment"-type commits.

This structure means that you can ``cd`` into the review data repository itself
and interact with it just as you would a normal Mercurial repository. You can
``push`` and ``pull`` to and from other people, backout changesets, and do
anything else you could with a normal Mercurial repository.