contribute.html fixes

R=r
http://go/go-review/1025019

doc/contribute.html

@@ -10,7 +10,7 @@
 <p>
 This document explains how to write a new package,
 how to test code, and how to contribute changes to the Go project.
-It assumes you have installed Go and Mercurial using the
+It assumes you have installed Go using the
 <a href="install.html">installation instructions</a>.  (Note that
 the <code>gccgo</code> frontend lives elsewhere;
 see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
@@ -335,7 +335,10 @@ in your client.
 It is best to keep unrelated changes in different change lists.
 In this example, we can include just the changes to package <code>math</code>
 by deleting the line mentioning <code>regexp.go</code>.
-If we did so, the template would now read:
+</p>
+
+<p>
+After editing, the template might now read:
 </p>
 
 <pre>
@@ -400,12 +403,77 @@ but then also synchronizes the local change list state against the new data.)</p
 
 <p>
 If files you were editing have changed, Mercurial does its best to merge the
-remote changes into your local changes.  It may leave some files to merge by hand.</p>
+remote changes into your local changes.  It may leave some files to merge by hand.
+</p>
+
+<p>
+For example, suppose you have edited <code>flag_test.go</code> but
+someone else has committed an independent change.
+When you run <code>hg sync</code>, you will get the (scary-looking) output
+(emphasis added):
 
 <pre>
-TODO(rsc): add example of merge
+$ hg sync
+adding changesets
+adding manifests
+adding file changes
+added 1 changeset with 2 changes to 2 files
+getting src/pkg/flag/flag.go
+couldn't find merge tool hgmerge
+merging src/pkg/flag/flag_test.go
+warning: conflicts during merge.
+<i>merging src/pkg/flag/flag_test.go failed!</i>
+1 file updated, 0 files merged, 0 files removed, 1 file unresolved
+use 'hg resolve' to retry unresolved file merges
+$ 
 </pre>
 
+<p>
+The only important part in that transcript is the italicized line:
+Mercurial failed to merge your changes with the independent change.
+When this happens, Mercurial leaves both edits in the file,
+marked by <code>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</code> and
+<code>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</code>.
+it is now your job to edit the file to combine them.
+Continuing the example, searching for those strings in <code>flag_test.go</code>
+might turn up:
+</p>
+
+<pre>
+	VisitAll(visitor);
+&lt;&lt;&lt;&lt;&lt;&lt;&lt; local
+	if len(m) != 7 {
+=======
+	if len(m) != 8 {
+&gt;&gt;&gt;&gt;&gt;&gt;&gt; other
+		t.Error("VisitAll misses some flags");
+</pre>
+
+<p>
+Mercurial doesn't show it, but suppose the original text that both edits
+started with was 6; you added 1 and the other change added 2,
+so the correct answer might now be 9.  If you edit the section
+to remove the markers and leave the correct code:
+</p>
+
+<pre>
+	VisitAll(visitor);
+	if len(m) != 9 {
+		t.Error("VisitAll misses some flags");
+</pre>
+
+<p>
+then that is enough.  There is no need to inform Mercurial
+that you have corrected the file.
+</p>
+
+<p>
+If you had been editing the file, say for debugging, but do not 
+care to preserve your changes, you can run 
+<code>hg revert flag_test.go</code> to abandon your
+changes.
+</p>
+
 <h3>Mail the change for review</h3>
 
 <p>To send out a change for review, run <code>hg mail</code> using the change list number
@@ -417,7 +485,7 @@ $ hg mail 99999
 
 <p>You can add to the <code>Reviewer:</code> and <code>CC:</code> lines
 using the <code>-r</code> or <code>--cc</code> options.
-The above example could have left the <code>Reviewer</code> and <code>CC</code>
+In the above example, we could have left the <code>Reviewer</code> and <code>CC</code>
 lines blank and then run:
 </p>
 
@@ -511,6 +579,8 @@ can check or test the code more.
 has been uploaded to the code review server.)
 The <code>submit</code> command submits the code.  You will be listed as the
 author, but the change message will also indicate who the committer was.
+Your local client will notice that the change has been submitted
+when you next run <code>hg sync</code>.
 </p>