--- a/docs/concepts.rst Mon Jun 14 23:38:00 2010 -0400
+++ b/docs/concepts.rst Tue Jun 15 00:21:03 2010 -0400
@@ -31,8 +31,118 @@
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:
+
+ 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.