From 9ad14c94db182dd3326e4c80053e0311f47700ce Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Fri, 6 Nov 2009 10:33:46 -0800
Subject: expand "this is not just mercurial" section

R=r
CC=go-dev
http://go/go-review/1024008
---
 doc/contribute.html | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/doc/contribute.html b/doc/contribute.html
index 633d1b1e4a..92190ca37c 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -173,24 +173,51 @@ Once your new code is tested and working,
 it's time to get it reviewed and submitted.
 </p>
 
-<h2>Installing the code review extension</h2>
+<h2>Code review</h2>
 
 <p>
 Changes to Go must be reviewed before they are submitted,
 no matter who makes the change.
+(In exceptional cases, such as fixing a build, the review can
+follow shortly after submitting.)
 A Mercurial extension helps manage the code review process.
 The extension is included in the Go source tree but needs
 to be added to your Mercurial configuration.
 </p>
 
+<h3>Caveat for Mercurial aficionados</h3>
+
 <p>
 <i>Using Mercurial with the code review extension is not the same
-as using it normally.</i>
+as using standard Mercurial.</i>
+</p>
+
+<p>
+The Go repository is maintained as a single line of reviewed changes;
+we prefer to avoid the complexity of Mercurial's arbitrary change graph.
+The code review extension helps here: its <code>hg submit</code> command
+automatically checks for and warns about the local repository
+being out of date compared to the remote one.
+The <code>hg submit</code> command also verifies other
+properties about the Go repository.
+For example, 
+it checks that Go code being checked in is formatted in the standard style,
+as defined by <a href="/cmd/gofmt">gofmt</a>,
+and it checks that the author of the code is properly recorded for
+<a href="#copyright">copyright purposes</a>.
 </p>
 
 <p>
-TODO(rsc): note here about model being different.
-Do not use <code>hg commit</code> if you are using the Mercurial extension.
+To help ensure changes are only created by <code>hg submit</code>,
+the code review extension disables the standard <code>hg commit</code>
+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.
 </p>
 
 <h3>Configure the extension</h3>
@@ -232,7 +259,7 @@ Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_coderevie
 
 <p>Edit your <a href="http://codereview.prom.corp.google.com/settings">code review settings</a>.
 Grab a nickname.
-Many people refer to set the Context option to 
+Many people prefer to set the Context option to 
 &ldquo;Whole file&rdquo; to see more context when reviewing changes.
 </p>
 
@@ -241,7 +268,7 @@ can use that nickname as a shorthand for naming reviewers and the CC list.
 For example, <code>rsc</code> is an alias for <code>rsc@golang.org</code>.
 </p>
 
-<h2>Changing code</h2>
+<h3>Make a change</h3>
 
 <p>
 The entire checked-out tree is writable.
@@ -255,8 +282,6 @@ or
 <code>hg mv</code>.
 </p>
 
-<h3>Create a change</h3>
-
 <p>When you are ready to send a change out for review, run</p>
 
 <pre>
-- 
cgit v1.2.3-54-g00ecf