diff options
-rw-r--r-- | doc/contribute.html | 538 |
1 files changed, 515 insertions, 23 deletions
diff --git a/doc/contribute.html b/doc/contribute.html index 8ab7e0d22..633d1b1e4 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -1,36 +1,528 @@ <!-- Contributing to the Go project --> -<h2 id="TODO">TODO(go-dev): Write this document</h2> +<!-- TODO(rsc): + Mention community resources like IRC, mailing lists, + change list email groups, etc. +--> + +<h2>Introduction</h2> + +<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 +<a href="install.html">installation instructions</a>. +</p> + +<p> +Before embarking on a significant change to an existing +package or the creation of a major new package, +it's a good idea to send mail to the <a href="FIXME">mailing list</a> +to let people know what you are thinking of doing. +Doing so helps avoid duplication of effort and +enables discussions about design before much code +has been written. +</p> + +<h2>Creating a new package</h2> + +<p> +The source code for the package with import path +<code>x/y</code> is, by convention, kept in the +directory <code>$GOROOT/src/pkg/x/y</code>. +</p> + +<h3>Makefile</h3> + +<p> +It would be nice to have Go-specific tools that +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>. +The basic form is illustrated by <a href="../src/pkg/container/vector/Makefile"><code>src/pkg/container/vector/Makefile</code></a>: +</p> + +<pre> +include $(GOROOT)/src/Make.$(GOARCH) + +TARG=container/vector +GOFILES=\ + intvector.go\ + stringvector.go\ + vector.go\ + +include $(GOROOT)/src/Make.pkg +</pre> + +<p> +The first and last lines <code>include</code> standard definitions and rules, +so that the body of the <code>Makefile</code> need only specify two variables. +</p> + +<p> +<code>TARG</code> is the target install path for the package, +the string that clients will use to import it. +This string should be the same as the directory +in which the <code>Makefile</code> appears, with the +<code>$GOROOT/src/pkg/</code> removed. +</p> + +<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 +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 +is included in the standard build. Then run: +<pre> +cd $GOROOT/src/pkg +./deps.bash +</pre> +<p> +to update the dependency file <code>Make.deps</code>. +</p> + +<p> +If you change the imports of an existing package, +you do not need to edit <code>$GOROOT/src/pkg/Makefile</code> +but you will still need to run <code>deps.bash</code> as above. +</p> + + +<h3>Go source files</h3> + +<p> +The first statement in each of the source files listed in the <code>Makefile</code> +should be <code>package <i>name</i></code>, where <code><i>name</i></code> +is the package's default name for imports. +(All files in a package must use the same <code><i>name</i></code>.) +Go's convention is that the package name is the last element of the +import path: the package imported as <code>"crypto/rot13"</code> +should be named <code>rot13</code>. +The Go tools impose a restriction that package names are unique +across all packages linked into a single binary, but that restriction +will be lifted soon. +</p> + +<p> +Go compiles all the source files in a package at once, so one file +can refer to constants, variables, types, and functions in another +file without special arrangement or declarations. +</p> + +<p> +Writing clean, idiomatic Go code is beyond the scope of this document. +<a href="effective_go.html">Effective Go</a> is an introduction to +that topic. +</p> + +<h2>Testing</h2> + +<p> +Go has a lightweight test framework known as <code>gotest</code>. +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> +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>. +</p> + +<p> +To run the test, run either <code>make test</code> or <code>gotest</code> +(they are equivalent). +To run only the tests in a single test file, for instance <code>one_test.go</code>, +run <code>gotest one_test.go</code>. +</p> + +<p> +Before sending code out for review, make sure everything +still works and the dependencies are right: +</p> + +<pre> +cd $GOROOT/src +./all.bash +</pre> + +<p> +The final line printed by <code>all.bash</code> should be of the form: +</p> + +<pre> +<i>N</i> known bugs; 0 unexpected bugs +</pre> + +<p> +The value of <i>N</i> varies over time, but the line must +say “<code>0 unexpected bugs</code>” and must not +add “<code>test output differs</code>.” +</p> + +<p> +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> + +<p> +Changes to Go must be reviewed before they are submitted, +no matter who makes the change. +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> <p> -Have to work on the tools first. +<i>Using Mercurial with the code review extension is not the same +as using it normally.</i> +</p> + +<p> +TODO(rsc): note here about model being different. +Do not use <code>hg commit</code> if you are using the Mercurial extension. +</p> + +<h3>Configure the extension</h3> + +[NOTE FOR BEFORE LAUNCH: <a href="http://www/~rsc/internal-hg.html">Read this instead</a>.] + +<p>Edit <code>$GOROOT/.hg/hgrc</code> to add:</p> + +<pre> +[extensions] +codereview = YOUR_GO_ROOT/lib/codereview/codereview.py +</pre> + +<p>Replace YOUR_GO_ROOT with the value of <code>$GOROOT</code>. +The Mercurial configuration file format does not allow environment variable substitution. +</p> + +<h3>Log in to the code review site.</h3> + +[NOTE FOR BEFORE LAUNCH: <a href="http://www/~rsc/internal-hg.html">Read this instead</a>.] + +<p> +The code review server uses a Google Account to authenticate. +(If you can use the account to +<a href="https://www.google.com/accounts/Login?hl=en&continue=http://www.google.com/">sign in at google.com</a>, +you can use it to sign in to the code review server.) +</p> + +<pre> +$ cd $GOROOT +$ hg codereview-login +Email (login for uploading to codereview.appspot.com): rsc@golang.org +Password for rsc@golang.org: + +Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_codereview.appspot.com +</pre> + +<h3>Configure your account settings.</h3> + +<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 +“Whole file” to see more context when reviewing changes. +</p> + +<p>Once you have chosen a nickname in the settings page, others +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> <p> -Text previously from the FAQ placed here for safekeeping. +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 +<code>hg add</code>, +<code>hg rm</code>, +<code>hg cp</code>, +or +<code>hg mv</code>. +</p> -<ol> -<li>If it's a significant change, discuss on the mailing list before embarking. +<h3>Create a change</h3> -<li>Check out the Go source code files. The library sources are in <code>go/src/pkg</code>. +<p>When you are ready to send a change out for review, run</p> -<li>Make changes; add tests as appropriate. Try to follow existing style, - including tabs for indentation, and no trailing whitespace. In - documentation comments for public declarations, use full sentences - and begin with the name of the thing being described, because godoc - (or other tools) may someday display these comments out of context. +<pre> +$ hg change +</pre> -<li>Write the <code>Makefile</code> by following existing examples. +<p>from any directory in your Go repository. +Mercurial will open a change description file in your editor. +(It uses the editor named by the <code>$EDITOR</code> environment variable, <code>vi</code> by default.) +The file will look like: +</p> -<li>Run <code>make</code> and <code>make test</code> in the affected - directories. +<pre> +# Change list. +# Lines beginning with # are ignored. +# Multi-line values should be indented. -<li>If you have added a new dependency, you may need to <code>cd go/src/lib; - ./deps.bash</code> to update the Make.deps file included in the Makefile. - For a new component, update the <code>Makefile</code> and then run - <code>deps.bash</code>. -<li><code>cd go/src; ./all.bash</code> +Reviewer: +CC: + +Description: + <enter description here> + +Files: + src/pkg/math/sin.go + src/pkg/math/tan.go + src/pkg/regexp/regexp.go +</pre> + +<p> +The <code>Reviewer</code> line lists the reviewers assigned +to this change, and the <code>CC</code> line lists people to +notify about the change. +These can be code review nicknames or arbitrary email addresses. +</p> + +<p> +Replace “<code><enter description here></code>” +with a description of your change. +The first line of the change description is conventionally +a one-line summary of the change and is used as the +subject for code review mail; the rest of the +description elaborates. +</p> + +<p> +The <code>Files</code> section lists all the modified files +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> + +<pre> +# Change list. +# Lines beginning with # are ignored. +# Multi-line values should be indented. + +Reviewer: r, rsc +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. + +Files: + src/pkg/math/sin.go + src/pkg/math/tan.go +</pre> + +<p> +The special sentence “Fixes issue 159.” associates +the change with issue 159 in the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>. +When this change is eventually submitted, the issue +tracker will automatically mark the issue as fixed. +</p> + +<p> +Save the file and exit the editor.</p> + +<p> +The code review server assigns your change an issue number and URL, +which <code>hg change</code> will print, something like: +</p> + +<pre> +CL created: http://codereview.appspot.com/99999 +</pre> + +<p> +If you need to re-edit the change description, +run <code>hg change 99999</code>. +</p> + +<p> +You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short). +</p> + + +<h3>Synchronize your client</h3> + +<p>While you were working, others might have submitted changes +to the repository. To update your client, run</p> + +<pre> +$ hg sync +</pre> + +<p>(For Mercurial fans, <code>hg sync</code> runs <code>hg pull -u</code> +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> + +<pre> +TODO(rsc): add example of merge +</pre> + +<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 +assigned during <code>hg change</code>:</p> + +<pre> +$ 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> +lines blank and then run: +</p> + +<pre> +$ hg mail -r r,rsc --cc math-nuts@swtch.com 99999 +</pre> + +<p>to achieve the same effect.</p> + +<p>Note that <code>-r</code> and <code>--cc</code> cannot be spelled <code>--r</code> or <code>-cc</code>.</p> + + +<h3>Reviewing code</h3> + +<p> +Running <code>hg mail</code> will send an email to you and the reviewers +asking them to visit the issue's URL and make coments on the change. +When done, the reviewer clicks “Publish and Mail comments” +to send comments back. +</p> + + +<h3>Revise and upload</h3> + +<p>You will probably revise your code in response to the reviewer comments. +When you have revised the code and are ready for another round of review, run +</p> + +<pre> +$ hg upload 99999 +</pre> + +<p>to upload the latest copy. +You might also visit the code review web page and reply to the comments, +letting the reviewer know that you've addressed them or explain why you +haven't. When you're done replying, click “Publish and Mail comments” +to send the line-by-line replies and any other comments. +A common acronym in such mails is <code>PTAL</code>: please take another look. +</p> +<p> +The reviewer can comment on the new copy, and the process repeats. +The reviewer approves the change by replying with a mail that says +<code>LGTM</code>: looks good to me. +</p> + +<h3>Submit the change</h3> + +<p> +Once the code has been <code>LGTM</code>'ed, it is time to submit +it to the Mercurial repository. +If you are a committer, you can run: +</p> + +<pre> +$ hg submit 99999 +</pre> + +<p> +This checks the change into the repository. +The change description will include a link to the code review, +and the code review will be updated with a link to the change +in the repository. +</p> + +<p> +If your local copy of the repository is out of date, +<code>hg submit</code> +will refuse the change: +</p> + +<pre> +$ hg submit 12345678 +local repository out of date; must sync before submit +</pre> + +<p> +If you are not a committer, you cannot submit the change directly. +Instead, a committer, usually the reviewer who said <code>LGTM</code>, +will run: +</p> + +<pre> +$ hg clpatch 99999 +$ hg submit 99999 +</pre> + +<p>The <code>clpatch</code> command imports your change 99999 into +the committer's local Mercurial client, at which point the committer +can check or test the code more. +(Anyone can run <code>clpatch</code> to try a change that +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. +</p> + + +<h3 id="copyright">Copyright</h3> + +<p>The standard copyright header for files in the Go tree is:</p> + +<pre> +// Copyright 2009 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. +</pre> + +<p> +Code you contribute should have this header. +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 +<a href="/AUTHORS"><code>AUTHORS</code></a> file, which defines +who “The Go Authors”—the copyright holders—are. +</p> + +<p> +When sending your first change list, you should prepare +and send a separate change list adding yourself to +<code>CONTRIBUTORS</code> and adding +the copyright holder for your code to <code>AUTHORS</code> if not already listed. +If you are the copyright holder, you will need to agree to +the <a href="http://code.google.com/legal/individual-cla-v1.0.html">individual contributor license agreement</a>, +which can be completed online; +if your organization is the copyright holder, the organization +will need to agree to the <a href="http://code.google.com/legal/corporate-cla-v1.0.html">corporate contributor license agreement</a>. +If the copyright holder for your code has already completed the +agreement in connection with another Google open source project, +it does not need to be completed again. +One of the Go developers at Google will approve and submit +this change after checking the list of people/organizations +that have completed the agreement. +</p> -<li>Once <code>all.bash</code> succeeds (output like - "N known bugs; 0 unexpected bugs" is OK), - <a href="/doc/contribute.html">submit a CL</a>. -</ol> |