hg-review/concepts.html @ 8058918d4932
adopt: Update site.
author |
Steve Losh <steve@stevelosh.com> |
date |
Mon, 23 Dec 2019 15:15:01 -0500 |
parents |
4ab3f1cb454a |
children |
(none) |
<!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.</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 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>distributed</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 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 used 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 one 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 signoffs of “yes” mean:</p>
<blockquote>
I approve of this changeset and think it should make its way to production.</blockquote>
<p>And signoffs of “No” mean:</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>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 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 in your project’s repository.</p>
<p>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 and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.7.
</div>
</body>
</html>