qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-21 21:44:40 -07:00
Code Releases Activity

doc: split contribute.html into code.html and contribute.html

Browse Source 
R=r
https://golang.org/cl/170042
This commit is contained in:
Russ Cox 2009-12-09 14:05:12 -08:00
parent 916533119e
commit d55abfd2c9
3 changed files with 270 additions and 222 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

204
doc/code.html Normal file
View File

@ -0,0 +1,204 @@
<!-- How to Write Go Code -->
<h2 id="Introduction">Introduction</h2>
<p>
This document explains how to write a new package
and how to test code.
It assumes you have installed Go using the
<a href="install.html">installation instructions</a>.
</p>
<p>
Before embarking on a change to an existing
package or the creation of a new package,
it's a good idea to send mail to the <a href="http://groups.google.com/group/golang-nuts">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 id="Community_resources">Community resources</h2>
<p>
For real-time help, there may be users or developers on
<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server.
</p>
<p>
The official mailing list for discussion of the Go language is
<a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>.
</p>
<p>
Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>.
</p>
<p>
For those who wish to keep up with development,
there is another mailing list, <a href="http://groups.google.com/group/golang-checkins">golang-checkins</a>,
that receives a message summarizing each checkin to the Go repository.
</p>
<h2 id="New_package">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 used in the Go source tree
is illustrated by <a href="../src/pkg/container/vector/Makefile"><code>src/pkg/container/vector/Makefile</code></a>:
</p>
<pre>
include ../../../Make.$(GOARCH)
TARG=container/vector
GOFILES=\
intvector.go\
stringvector.go\
vector.go\
include ../../../Make.pkg
</pre>
<p>
Outside the Go source tree (for personal packages), the standard form is
</p>
<pre>
include $(GOROOT)/src/Make.$(GOARCH)
TARG=mypackage
GOFILES=\
my1.go\
my2.go\
include $(GOROOT)/src/Make.pkg
</pre>
<p>
The first and last lines <code>include</code> standard definitions and rules.
Packages maintained in the standard Go tree use a relative path (instead of
<code>$(GOROOT)/src</code>) so that <code>make</code> will work correctly
even if <code>$(GOROOT)</code> contains spaces.
This makes it easy for programmers to try Go.
</p>
<p>
<code>TARG</code> is the target install path for the package,
the string that clients will use to import it.
Inside the Go tree, this string should be the same as the directory
in which the <code>Makefile</code> appears, with the
<code>$GOROOT/src/pkg/</code> prefix removed.
Outside the Go tree, you can use any <code>TARG</code> you
want that doesn't conflict with the standard Go package names.
A common convention is to use an identifying top-level name
to group your packages: <code>myname/tree</code>, <code>myname/filter</code>, etc.
Note that even if you keep your package source outside the
Go tree, running <code>make install</code> installs your
package binaries in the standard location&mdash;<code>$GOROOT/pkg</code>&mdash;to
make it easy to find them.
</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>
If you create a new package directory in the Go tree, 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>.
(This happens automatically each time you run <code>all.bash</code>
or <code>make.bash</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>.
At the moment, 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 id="Testing">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>
If your change affects performance, add a <code>Benchmark</code> function
(see the <a href="/cmd/gotest/">gotest command documentation</a>)
and run it using <code>gotest -benchmarks=.</code>.
</p>
<p>
Once your new code is tested and working,
it's time to get it <a href="contribute.html">reviewed and submitted</a>.
</p>

287
doc/contribute.html
View File

@ -3,175 +3,20 @@
<h2 id="Introduction">Introduction</h2> <h2 id="Introduction">Introduction</h2>
<p> <p>
This document explains how to write a new package, This document explains how to contribute changes to the Go project.
how to test code, and how to contribute changes to the Go project.
It assumes you have installed Go using the It assumes you have installed Go using the
<a href="install.html">installation instructions</a>. (Note that <a href="install.html">installation instructions</a> and
the <code>gccgo</code> frontend lives elsewhere; have <a href="code.html">written and tested your code</a>.
(Note that the <code>gccgo</code> frontend lives elsewhere;
see <a href="gccgo_contribute.html">Contributing to gccgo</a>.) see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
</p> </p>
<p> <h2 id="Testing">Testing redux</h2>
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="http://groups.google.com/group/golang-nuts">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 id="Community_resources">Community resources</h2>
<p> <p>
For real-time help, there may be users or developers on You've <a href="code.html">written and tested your code</a>, but
<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server. before sending code out for review, run all the tests for the whole
</p> tree to make sure the changes don't break other packages or programs:
<p>
The official mailing list for discussion of the Go language is
<a href="http://groups.google.com/group/golang-nuts">Go Nuts</a>.
</p>
<p>
Bugs can be reported using the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>.
</p>
<p>
For those who wish to keep up with development,
there is another mailing list, <a href="http://groups.google.com/group/golang-checkins">golang-checkins</a>,
that receives a message summarizing each checkin to the Go repository.
</p>
<h2 id="New_package">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 ../../../Make.$(GOARCH)
TARG=container/vector
GOFILES=\
intvector.go\
stringvector.go\
vector.go\
include ../../../Make.pkg
</pre>
<p>
The first and last lines <code>include</code> standard definitions and rules,
<code>$(GOROOT)/src/Make.$(GOARCH)</code> and <code>$(GOROOT)/src/Make.pkg</code>,
so that the body of the <code>Makefile</code> need only specify two variables.
For packages to be installed in the Go tree, use a relative path instead of
<code>$(GOROOT)/src</code>, so that make will work correctly even if <code>$(GOROOT)</code> contains spaces.
</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>.
(This happens automatically each time you run <code>all.bash</code>
or <code>make.bash</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 id="Testing">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> </p>
<pre> <pre>
@ -193,10 +38,6 @@ say &ldquo;<code>0 unexpected bugs</code>&rdquo; and must not
add &ldquo;<code>test output differs</code>.&rdquo; add &ldquo;<code>test output differs</code>.&rdquo;
</p> </p>
<p>
Once your new code is tested and working,
it's time to get it reviewed and submitted.
</p>
<h2 id="Code_review">Code review</h2> <h2 id="Code_review">Code review</h2>
@ -252,10 +93,15 @@ the Mercurial Queues extension.
<pre> <pre>
[extensions] [extensions]
codereview = YOUR_GO_ROOT/lib/codereview/codereview.py codereview = YOUR_GO_ROOT/lib/codereview/codereview.py
[ui]
username = Your Name &lt;you@server.dom&gt;
</pre> </pre>
<p>Replace YOUR_GO_ROOT with the value of <code>$GOROOT</code>. <p>Replace YOUR_GO_ROOT with the value of <code>$GOROOT</code>.
The Mercurial configuration file format does not allow environment variable substitution. The Mercurial configuration file format does not allow environment variable substitution.
The <code>username</code> information will not be used unless
you are a committer (see below), but Mercurial complains if it is missing.
</p> </p>
<h3>Log in to the code review site.</h3> <h3>Log in to the code review site.</h3>
@ -264,7 +110,12 @@ The Mercurial configuration file format does not allow environment variable subs
The code review server uses a Google Account to authenticate. The code review server uses a Google Account to authenticate.
(If you can use the account to (If you can use the account to
<a href="https://www.google.com/accounts/Login?hl=en&amp;continue=http://www.google.com/">sign in at google.com</a>, <a href="https://www.google.com/accounts/Login?hl=en&amp;continue=http://www.google.com/">sign in at google.com</a>,
you can use it to sign in to the code review server.) you can use it to sign in to the code review server.
The email address you use on the Code Review site
will be recorded in the <a href="http://code.google.com/p/go/source/list">Mercurial change log</a>
and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file.
You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a>
associated with any address where you receive email.
</p> </p>
<pre> <pre>
@ -369,7 +220,7 @@ After editing, the template might now read:
# Lines beginning with # are ignored. # Lines beginning with # are ignored.
# Multi-line values should be indented. # Multi-line values should be indented.
Reviewer: r, rsc Reviewer: golang-dev@googlegroups.com
CC: math-nuts@swtch.com CC: math-nuts@swtch.com
Description: Description:
@ -475,7 +326,7 @@ might turn up:
<p> <p>
Mercurial doesn't show it, but suppose the original text that both edits 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, 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 so the correct answer might now be 9. First, edit the section
to remove the markers and leave the correct code: to remove the markers and leave the correct code:
</p> </p>
@ -486,15 +337,19 @@ to remove the markers and leave the correct code:
</pre> </pre>
<p> <p>
then that is enough. There is no need to inform Mercurial Then ask Mercurial to mark the conflict as resolved:
that you have corrected the file.
</p> </p>
<pre>
$ hg resolve -m flag_test.go
</pre>
<p> <p>
If you had been editing the file, say for debugging, but do not If you had been editing the file, say for debugging, but do not
care to preserve your changes, you can run care to preserve your changes, you can run
<code>hg revert flag_test.go</code> to abandon your <code>hg revert flag_test.go</code> to abandon your
changes. changes, but you may still need to run
<code>hg resolve -m</code> to mark the conflict resolved.
</p> </p>
<h3>Mail the change for review</h3> <h3>Mail the change for review</h3>
@ -513,7 +368,7 @@ lines blank and then run:
</p> </p>
<pre> <pre>
$ hg mail -r r,rsc --cc math-nuts@swtch.com 99999 $ hg mail -r golang-dev@googlegroups.com --cc math-nuts@swtch.com 99999
</pre> </pre>
<p>to achieve the same effect.</p> <p>to achieve the same effect.</p>
@ -580,7 +435,7 @@ will refuse the change:
</p> </p>
<pre> <pre>
$ hg submit 12345678 $ hg submit 99999
local repository out of date; must sync before submit local repository out of date; must sync before submit
</pre> </pre>
@ -609,56 +464,44 @@ when you next run <code>hg sync</code>.
<h3 id="copyright">Copyright</h3> <h3 id="copyright">Copyright</h3>
<p>The standard copyright header for files in the Go tree is:</p> <p>Files in the Go repository don't list author names,
both to avoid clutter and to avoid having to keep the lists up to date.
Instead, your name will appear in the <a href="http://code.google.com/p/go/source/list">Mercurial change log</a>
and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file
and perhaps the <a href="/AUTHORS"><code>AUTHORS</code></a> file.
</p>
<p>The <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file
defines who the Go contributors&mdash;the people&mdash;are;
the <a href="/AUTHORS"><code>AUTHORS</code></a> file, which defines
who &ldquo;The Go Authors&rdquo;&mdash;the copyright holders&mdash;are.
The Go developers at Google will update these files when submitting
your first change.
In order for them to do that, you need to have completed one of the
contributor license agreements:
<ul>
<li>
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.
</li>
<li>
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.)
</li>
</ul>
<p>
This rigmarole needs to be done only for your first submission.
</p>
<p>Code that you contribute should use the standard copyright header:</p>
<pre> <pre>
// Copyright 2009 The Go Authors. All rights reserved. // Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style // Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file. // license that can be found in the LICENSE file.
</pre> </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&mdash;the people&mdash;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 &ldquo;The Go Authors&rdquo;&mdash;the copyright holders&mdash;are.
</p>
<p>
When sending your first change list, you need to do two extra things before your
code can be accepted.
</p>
<ol>
<li>
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.)
<li>
Send mail, or include information in the change list description,
notifying us how you should be represented in the <code>CONTRIBUTORS</code>
and <code>AUTHORS</code> files so we can add your information to
them. Specifically, tell us either that you've completed the
individual agreement or tell us the name of your organization once
it has completed the corporate agreement. One of the Go developers
at Google will add you to <code>CONTRIBUTORS</code> and, if
appropriate, <code>AUTHORS</code> after verifying that the agreement
has been completed. We will use the email address you use on
codereview.appspot.com as the email address in these files.</ol>
<p>
This rigamarole needs to be done only for your first submission.
</p>
<p>
Once the code is ready to be committed,
one of the Go developers at Google will approve and submit
your change.
</p>

1
lib/godoc/godoc.html
View File

@ -91,6 +91,7 @@
<li class="blank">&nbsp;</li> <li class="blank">&nbsp;</li>
<li class="navhead">How To</li> <li class="navhead">How To</li>
<li><a href="/doc/install.html">Install Go</a></li> <li><a href="/doc/install.html">Install Go</a></li>
<li><a href="/doc/code.html">Write code</a></li>
<li><a href="/doc/contribute.html">Contribute code</a></li> <li><a href="/doc/contribute.html">Contribute code</a></li>
<li class="blank">&nbsp;</li> <li class="blank">&nbsp;</li>