doc: codereview + Mercurial Queues

R=rsc, r
CC=golang-dev
http://codereview.appspot.com/1238044

Committer: Russ Cox <rsc@golang.org>

2 files changed, 115 insertions, 4 deletions

diff --git a/doc/codereview_with_mq.html b/doc/codereview_with_mq.html
new file mode 100644
index 000000000..7b2e0f3bf
--- /dev/null
+++ b/doc/codereview_with_mq.html
@@ -0,0 +1,113 @@
+<!-- Using Mercurial Queues with Codereview -->
+
+<h2 id="Introduction">Introduction</h2>
+
+<p>
+The Mercurial Queues extension (<code>mq</code>) provides a mechanism for
+managing patches on top of a Mercurial repository and is described in detail
+in Chapters
+<a href="http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html">12</a>
+and <a href="http://hgbook.red-bean.com/read/advanced-uses-of-mercurial-queues.html">13</a>
+of <a href="http://hgbook.red-bean.com/read/">Mercurial: The Definitive Guide</a>.
+This document explains how to use <code>mq</code> in conjunction
+with the <code>codereview</code> Mercurial extension described in the
+instructions for <a href="contribute.html">contributing to the Go project</a>.
+It assumes you have read those instructions.
+</p>
+
+<h2>Configuration</h2>
+
+<p>
+To enable <code>mq</code> edit either <code>$HOME/.hgrc</code> (to enable it
+for all of your repositories) or <code>$GOROOT/.hg/hgrc</code> (to enable it for the
+repository at <code>$GOROOT</code>) to add:</p>
+
+<pre>
+[extensions]
+mq=
+</pre>
+
+<p>
+Since pulling, pushing, updating and committing while <code>mq</code> patches
+are applied can damage your repository or a remote one, add these lines to
+prevent that case: 
+</p>
+
+<pre>
+[hooks]
+# Prevent "hg pull" if MQ patches are applied.
+prechangegroup.mq-no-pull = ! hg qtop > /dev/null 2>&1
+# Prevent "hg push" if MQ patches are applied.
+preoutgoing.mq-no-push = ! hg qtop > /dev/null 2>&1
+# Prevent "hg update" if MQ patches are applied.
+preupdate.mq-no-update = ! hg qtop > /dev/null 2>&1
+</pre>
+
+<h2>Making a change</h2>
+
+<p>
+The entire checked-out tree is writable and you can use <code>mq</code>,
+as documented in Chapter
+<a href="http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html">12</a>
+of "The Guide",
+to implement your change as a single patch or a series of patches.
+
+</p>
+
+<p>When you are ready to send a change out for review, run</p>
+
+<pre>
+$ hg change
+</pre>
+
+<p>from any directory in your Go repository with all of the <code>mq</code> patches relevant to your
+change applied and then proceed as instructed in <a href="contribute.html">contributing
+to the Go project</a>.
+</p>
+
+<p>
+The change number reported by <code>hg change</code>, preceded by a <code>+</code>,
+can be used as an <code>mq</code> patch guard to assist in controlling which patches
+are applied as described in Chapter
+<a href="http://hgbook.red-bean.com/read/advanced-uses-of-mercurial-queues.html">13</a>
+of "The Guide".
+For example, the command:
+</p>
+
+<pre>
+for p in $(hg qapplied); do hg qguard $p +99999; done
+</pre>
+
+<p>
+will apply the guard <code>+99999</code> guard to all currently applied <code>mq</code>
+patches.
+</p>
+
+<h2>Synchronizing your client</h2>
+
+<p>While you were working, others might have submitted changes
+to the repository and, as explained in <a href="contribute.html">contributing
+to the Go project</a>, it is necessary to synchronize your repository using
+<code>hg sync</code>before sending your change list for review.
+Because <code>hg sync</code> runs <code>hg pull -u</code>,
+you should not run <code>hg sync</code> while <code>mq</code> patches are
+applied. Instead
+pop all your patches before running <code>hg sync</code> and reapply them after
+it has completed.
+</p>
+
+<p>
+When reapplying the patches, you may need to resolve conflicts
+as described in <a href="contribute.html">contributing to the Go project</a>.
+</p>
+
+<h2>Mailing the change for review</h2>
+
+<p>
+You should have all of the <code>mq</code> patches relevant to your
+change applied when you run <code>hg mail</code>.
+
+<h2>Submitting the change after the review</h2>
+
+If you are a committer, you should have all of the <code>mq</code> patches relevant to your
+change applied when you run <code>hg commit</code>.
diff --git a/doc/contribute.html b/doc/contribute.html
index f7fa4490b..6814274ba 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -103,10 +103,8 @@ command.
 </p>
 
 <p>
-Mercurial power users: To allow Go contributors to take advantage of
-Mercurial's functionality for local revision control, it might be interesting
-to explore how the code review extension can be made to work alongside
-the Mercurial Queues extension.
+Mercurial power users: if you prefer to use the Mercurial Queues extension, see
+<a href="codereview_with_mq.html">Using Mercurial Queues with Codereview</a>.
 </p>
 
 <h3>Configure the extension</h3>