# HG changeset patch # User Steve Losh # Date 1276575663 14400 # Node ID 9307f4023849bb805eb407c6a67fb72f21e9a09e # Parent cf64f6f74ad3791e4957dd7c4d60d529a6dcd517 docs: work on the concepts doc diff -r cf64f6f74ad3 -r 9307f4023849 docs/concepts.rst --- 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 `_, but some other +popular tools include: + +* `Rietveld `_ +* `Reviewboard `_ +* `Gerrit `_ +* `Code Collaborator `_ + +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 `_ and +`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 `_ and `Mercurial `_ +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.