diff options
| -rw-r--r-- | doc/contribute.html | 108 |
1 files changed, 89 insertions, 19 deletions
diff --git a/doc/contribute.html b/doc/contribute.html index 890df3dac..5e40c9e12 100644 --- a/doc/contribute.html +++ b/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>.) @@ -38,7 +38,7 @@ directory <code>$GOROOT/src/pkg/x/y</code>. <p> 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 <code>make</code>. Thus, the first file to create in a new package directory is usually the <code>Makefile</code>. @@ -73,13 +73,13 @@ in which the <code>Makefile</code> appears, with the <p> <code>GOFILES</code> is a list of source files to compile to create the package. The trailing <code>\</code> characters -allow the list to be split onto multiple lines +allow the list to be split onto multiple lines for easy sorting. </p> <p> After creating a new package directory, add it to the list in -<code>$GOROOT/src/pkg/Makefile</code> so that it +<code>$GOROOT/src/pkg/Makefile</code> so that it is included in the standard build. Then run: <pre> cd $GOROOT/src/pkg @@ -131,12 +131,12 @@ You write a test by creating a file with a name ending in <code>_test.go</code> that contains functions named <code>TestXXX</code> with signature <code>func (t *testing.T)</code>. The test framework runs each such function; if the function calls a failure function such as <code>t.Error</code> or <code>t.Fail</code>, the test is considered to have failed. -The <a href="/cmd/gotest/">gotest command documentation</a> +The <a href="/cmd/gotest/">gotest command documentation</a> and the <a href="/pkg/testing/">testing package documentation</a> give more detail. </p> <p> -The <code>*_test.go</code> files should not be listed in the <code>Makefile</code>. +The <code>*_test.go</code> files should not be listed in the <code>Makefile</code>. </p> <p> @@ -202,7 +202,7 @@ 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, +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 @@ -261,7 +261,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 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. </p> @@ -276,7 +276,7 @@ For example, <code>rsc</code> is an alias for <code>rsc@golang.org</code>. 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 <code>hg add</code>, <code>hg rm</code>, <code>hg cp</code>, @@ -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 <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> @@ -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.)</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> +$ 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><<<<<<<</code> and +<code>>>>>>>></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); +<<<<<<< local + if len(m) != 7 { +======= + if len(m) != 8 { +>>>>>>> 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> -TODO(rsc): add example of merge + 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 @@ -416,8 +484,8 @@ $ hg mail 99999 </pre> <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> +using the <code>-r</code> or <code>--cc</code> options. +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> @@ -526,11 +596,11 @@ author, but the change message will also indicate who the committer was. <p> Code you contribute should have this header. -You need to be listed in the +You need to be listed in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> 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 <a href="/AUTHORS"><code>AUTHORS</code></a> file, which defines who “The Go Authors”—the copyright holders—are. </p> |