hg-review/concepts.html @ ea24eb13e78b
hg-review: Update documentation.
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Mon, 05 Jul 2010 23:39:33 -0400 |
| parents | 75e16ecaa86d |
| children | 8b81f9393b01 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Concepts — hg-review vpre-alpha documentation</title> <link rel="stylesheet" href="_static/review.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: 'pre-alpha', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="hg-review vpre-alpha documentation" href="index.html" /> <link rel="next" title="Web Interface" href="webui.html" /> <link rel="prev" title="Overview" href="overview.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="webui.html" title="Web Interface" accesskey="N">next</a> |</li> <li class="right" > <a href="overview.html" title="Overview" accesskey="P">previous</a> |</li> <li><a href="index.html">hg-review vpre-alpha documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="concepts"> <h1>Concepts<a class="headerlink" href="#concepts" title="Permalink to this headline">¶</a></h1> <p>You’re not perfect.</p> <p>Your code is not perfect.</p> <p>If you’re the only person that’s reading your code, it’s wrong. Period.</p> <p>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.</p> <div class="section" id="code-review-basics"> <h2>Code Review Basics<a class="headerlink" href="#code-review-basics" title="Permalink to this headline">¶</a></h2> <p>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.</p> <p>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?”</p> <p>Code review tools (like hg-review) exist to make reviewing other people’s code easier.</p> <p>Their goal is to make it as easy as possible to tell another developer: “No, you did <em>this</em> wrong. Fix it.”</p> </div> <div class="section" id="other-code-review-tools"> <h2>Other Code Review Tools<a class="headerlink" href="#other-code-review-tools" title="Permalink to this headline">¶</a></h2> <p>There are a lot of “code review tools” out there.</p> <p>The primary author of hg-review has a lot of experience with <a class="reference external" href="http://www.atlassian.com/software/crucible/">Atlassian Crucible</a>, but some other popular tools include:</p> <ul class="simple"> <li><a class="reference external" href="http://codereview.appspot.com/">Rietveld</a></li> <li><a class="reference external" href="http://www.reviewboard.org/">Reviewboard</a></li> <li><a class="reference external" href="http://code.google.com/p/gerrit/">Gerrit</a></li> <li><a class="reference external" href="http://smartbear.com/codecollab.php">Code Collaborator</a></li> </ul> <p>All of these tools try to accomplish the same goal: making it easy for developers to tell each other how to write better code.</p> <p>hg-review has the same goal, but it goes about it a little differently.</p> </div> <div class="section" id="distributed-code-review"> <h2>Distributed Code Review<a class="headerlink" href="#distributed-code-review" title="Permalink to this headline">¶</a></h2> <p>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 <em>centralized</em> systems like <a class="reference external" href="http://subversion.apache.org/">Subversion</a> and <a class="reference external" href="http://www.nongnu.org/cvs/">CVS</a>.</p> <p>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.</p> <p>In the past half-decade or so there has been a move toward <em>decentralized</em> or <em>distrubuted</em> version control systems. With these systems you commit to your local machine and then <em>push</em> and <em>pull</em> your commits to other people.</p> <p>Code review tools, however, seem to have remained rooted in the “centralized server” approach. Even the tools that support decentralized version control systems like <a class="reference external" href="http://git-scm.com">git</a> and <a class="reference external" href="http://hg-scm.org">Mercurial</a> rely on a central server to store the code review data.</p> <p>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.</p> <p>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.</p> <p>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.</p> </div> <div class="section" id="review-data"> <h2>Review Data<a class="headerlink" href="#review-data" title="Permalink to this headline">¶</a></h2> <p>hg-review tracks two kinds of code review data: comments and signoffs.</p> <p>Comments are simple comments that people make about changesets. People can comment on:</p> <ul class="simple"> <li>A changeset as a whole.</li> <li>A specific file within a changeset.</li> <li>One or more lines of a specific file within a changeset.</li> </ul> <p>Signoffs, on the other hand, <em>always</em> apply to a changeset as a whole. Each person can have on signoff for any particular changeset (though they can edit their signoff later).</p> <p>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:</p> <blockquote> I approve of this changeset and think it should make its way to production.</blockquote> <p>for signoffs of “Yes” and:</p> <blockquote> 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.</blockquote> <p>for signoffs of “No.”</p> <p>Signoffs of “neutral” might mean:</p> <blockquote> This changeset doesn’t really impact me, so I don’t care.</blockquote> <p>or perhaps:</p> <blockquote> I’ve looked at this code but don’t have the expertise to provide a useful opinion.</blockquote> </div> <div class="section" id="repository-structure"> <h2>Repository Structure<a class="headerlink" href="#repository-structure" title="Permalink to this headline">¶</a></h2> <p>While it’s not necessary to know exactly how the guts of hg-review work, it <em>is</em> helpful to understand the basic idea behind it.</p> <p>Let’s say you have a project with a Mercurial repository in <tt class="docutils literal"><span class="pre">~/src/yourproject/</span></tt> and you’d like to start using hg-review with it.</p> <p>The first thing to understand is that Mercurial itself stores data about this local repository in <tt class="docutils literal"><span class="pre">~/src/yourproject/.hg/</span></tt>, 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.</p> <p>hg-review creates a <em>separate</em> Mercurial repository to keep track of its data. It stores this repository in <tt class="docutils literal"><span class="pre">~/src/yourproject/.hg/review/</span></tt>.</p> <p>Because this is inside of Mercurial’s internal <tt class="docutils literal"><span class="pre">.hg</span></tt> directory of your project, changes to the review data (like comments and signoffs) won’t be tracked by your project’s repository.</p> <p>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.</p> <p>This structure means that you can <tt class="docutils literal"><span class="pre">cd</span></tt> into the review data repository itself and interact with it just as you would a normal Mercurial repository. You can <tt class="docutils literal"><span class="pre">push</span></tt> and <tt class="docutils literal"><span class="pre">pull</span></tt> to and from other people, backout changesets, and do anything else you could with a normal Mercurial repository.</p> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="#">Concepts</a><ul> <li><a class="reference external" href="#code-review-basics">Code Review Basics</a></li> <li><a class="reference external" href="#other-code-review-tools">Other Code Review Tools</a></li> <li><a class="reference external" href="#distributed-code-review">Distributed Code Review</a></li> <li><a class="reference external" href="#review-data">Review Data</a></li> <li><a class="reference external" href="#repository-structure">Repository Structure</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="overview.html" title="previous chapter">Overview</a></p> <h4>Next topic</h4> <p class="topless"><a href="webui.html" title="next chapter">Web Interface</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/concepts.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="webui.html" title="Web Interface" >next</a> |</li> <li class="right" > <a href="overview.html" title="Overview" >previous</a> |</li> <li><a href="index.html">hg-review vpre-alpha documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2010, Steve Losh. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.7. </div> </body> </html>