From 696e802329af81794cf1020729e8aac3a9b4888a Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Sat, 7 Nov 2009 18:56:00 -0800 Subject: [PATCH] contribute.html fixes R=r http://go/go-review/1025019 --- doc/contribute.html | 108 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 89 insertions(+), 19 deletions(-) diff --git a/doc/contribute.html b/doc/contribute.html index 890df3dac7f..5e40c9e12fe 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -10,7 +10,7 @@

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 installation instructions. (Note that the gccgo frontend lives elsewhere; see Contributing to gccgo.) @@ -38,7 +38,7 @@ directory $GOROOT/src/pkg/x/y.

It would be nice to have Go-specific tools that -inspect the source files to determine what to build and in +inspect the source files to determine what to build and in what order, but for now, Go uses GNU make. Thus, the first file to create in a new package directory is usually the Makefile. @@ -73,13 +73,13 @@ in which the Makefile appears, with the

GOFILES is a list of source files to compile to create the package. The trailing \ characters -allow the list to be split onto multiple lines +allow the list to be split onto multiple lines for easy sorting.

After creating a new package directory, add it to the list in -$GOROOT/src/pkg/Makefile so that it +$GOROOT/src/pkg/Makefile so that it is included in the standard build. Then run: 

 cd $GOROOT/src/pkg
@@ -131,12 +131,12 @@ You write a test by creating a file with a name ending in _test.go
 that contains functions named TestXXX with signature func (t *testing.T).
 The test framework runs each such function;
 if the function calls a failure function such as t.Error or t.Fail, the test is considered to have failed.
-The gotest command documentation 
+The gotest command documentation
 and the testing package documentation give more detail.
 

 
 

-The *_test.go files should not be listed in the Makefile.  
+The *_test.go files should not be listed in the Makefile.
 

 
 

@@ -202,7 +202,7 @@ automatically checks for and warns about the local repository
 being out of date compared to the remote one.
 The hg submit command also verifies other
 properties about the Go repository.
-For example, 
+For example,
 it checks that Go code being checked in is formatted in the standard style,
 as defined by gofmt,
 and it checks that the author of the code is properly recorded for
@@ -261,7 +261,7 @@ Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_coderevie
 
 
Edit your code review settings.
 Grab a nickname.
-Many people prefer to set the Context option to 
+Many people prefer to set the Context option to
 “Whole file” to see more context when reviewing changes.
 

 
@@ -276,7 +276,7 @@ For example, rsc is an alias for rsc@golang.org.
 The entire checked-out tree is writable.
 If you need to edit files, just edit them: Mercurial will figure out which ones changed.
 You do need to inform Mercurial of added, removed, copied, or renamed files,
-by running 
+by running
 hg add,
 hg rm,
 hg cp,
@@ -301,8 +301,8 @@ The file will look like:
 # Lines beginning with # are ignored.
 # Multi-line values should be indented.
 
-Reviewer: 
-CC: 
+Reviewer:
+CC:
 
 Description:
 	<enter description here>
@@ -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 math
 by deleting the line mentioning regexp.go.
-If we did so, the template would now read:
+

+
+

+After editing, the template might now read:
 

 
 
@@ -348,7 +351,7 @@ CC: math-nuts@swtch.com
 
 Description:
 	Sin, Cos, Tan: improved precision for very large arguments
-	
+
 	See Bimmler and Shaney, ``Extreme sinusoids,'' J. Math 3(14).
 	Fixes issue 159.
 
@@ -400,12 +403,77 @@ but then also synchronizes the local change list state against the new data.)

 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.

+remote changes into your local changes.  It may leave some files to merge by hand.
+

+
+

+For example, suppose you have edited flag_test.go but
+someone else has committed an independent change.
+When you run hg sync, you will get the (scary-looking) output
+(emphasis added):
 
 
-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.
+merging src/pkg/flag/flag_test.go failed!
+1 file updated, 0 files merged, 0 files removed, 1 file unresolved
+use 'hg resolve' to retry unresolved file merges
+$ 
 

 
+

+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 <<<<<<< and
+>>>>>>>.
+it is now your job to edit the file to combine them.
+Continuing the example, searching for those strings in flag_test.go
+might turn up:
+

+
+
+	VisitAll(visitor);
+<<<<<<< local
+	if len(m) != 7 {
+=======
+	if len(m) != 8 {
+>>>>>>> other
+		t.Error("VisitAll misses some flags");
+

+
+

+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:
+

+
+
+	VisitAll(visitor);
+	if len(m) != 9 {
+		t.Error("VisitAll misses some flags");
+

+
+

+then that is enough.  There is no need to inform Mercurial
+that you have corrected the file.
+

+
+

+If you had been editing the file, say for debugging, but do not 
+care to preserve your changes, you can run 
+hg revert flag_test.go to abandon your
+changes.
+

+
 
Mail the change for review

 
 
To send out a change for review, run hg mail using the change list number
@@ -416,8 +484,8 @@ $ hg mail 99999
 

 
 
You can add to the Reviewer: and CC: lines
-using the -ror --cc options.
-The above example could have left the Reviewer and CC
+using the -r or --cc options.
+In the above example, we could have left the Reviewer and CC
 lines blank and then run:
 

 
@@ -511,6 +579,8 @@ can check or test the code more.
 has been uploaded to the code review server.)
 The submit 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 hg sync.
 

 
 
@@ -526,11 +596,11 @@ author, but the change message will also indicate who the committer was.
 
 

 Code you contribute should have this header.
-You need to be listed in the 
+You need to be listed in the
 CONTRIBUTORS file,
 which defines who the Go contributors—the people—are;
 and the copyright holder for the code you submit (either you or the
-organization you work for) needs to be listed in the 
+organization you work for) needs to be listed in the
 AUTHORS file, which defines
 who “The Go Authors”—the copyright holders—are.