You’re not perfect.
Your code is not perfect.
If you’re the only person that’s reading your code, it’s wrong.
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 be looking at it.
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.”
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:
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.
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 distributed 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 without sacrificing any functionality.
It also means that the full power of Mercurial (such as tracking history and signing changesets with GPG) can be used on the 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:
Signoffs, on the other hand, always apply to a changeset as a whole. Each person can have one 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 signoffs of “yes” mean:
I approve of this changeset and think it should make its way to production.
And signoffs of “No” mean:
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.
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.
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 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 in your project’s repository.
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.