From d55abfd2c9cd96f8e4c1b61a9b57c88d3f3bcd37 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 9 Dec 2009 14:05:12 -0800 Subject: [PATCH] doc: split contribute.html into code.html and contribute.html R=r https://golang.org/cl/170042 --- doc/code.html | 204 ++++++++++++++++++++++++++++++ doc/contribute.html | 287 ++++++++++--------------------------------- lib/godoc/godoc.html | 1 + 3 files changed, 270 insertions(+), 222 deletions(-) create mode 100644 doc/code.html diff --git a/doc/code.html b/doc/code.html new file mode 100644 index 00000000000..178fca131f7 --- /dev/null +++ b/doc/code.html @@ -0,0 +1,204 @@ + + +

Introduction

+ +

+This document explains how to write a new package +and how to test code. +It assumes you have installed Go using the +installation instructions. +

+ +

+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 mailing list +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. +

+ +

Community resources

+ +

+For real-time help, there may be users or developers on +#go-nuts on the Freenode IRC server. +

+ +

+The official mailing list for discussion of the Go language is +Go Nuts. +

+ +

+Bugs can be reported using the Go issue tracker. +

+ +

+For those who wish to keep up with development, +there is another mailing list, golang-checkins, +that receives a message summarizing each checkin to the Go repository. +

+ + +

Creating a new package

+ +

+The source code for the package with import path +x/y is, by convention, kept in the +directory $GOROOT/src/pkg/x/y. +

+ +

Makefile

+ +

+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 make. +Thus, the first file to create in a new package directory is +usually the Makefile. +The basic form used in the Go source tree +is illustrated by src/pkg/container/vector/Makefile: +

+ +
+include ../../../Make.$(GOARCH)
+
+TARG=container/vector
+GOFILES=\
+	intvector.go\
+	stringvector.go\
+	vector.go\
+
+include ../../../Make.pkg
+
+ +

+Outside the Go source tree (for personal packages), the standard form is +

+ +
+include $(GOROOT)/src/Make.$(GOARCH)
+
+TARG=mypackage
+GOFILES=\
+	my1.go\
+	my2.go\
+
+include $(GOROOT)/src/Make.pkg
+
+ +

+The first and last lines include standard definitions and rules. +Packages maintained in the standard Go tree use a relative path (instead of +$(GOROOT)/src) so that make will work correctly +even if $(GOROOT) contains spaces. +This makes it easy for programmers to try Go. +

+ +

+TARG 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 Makefile appears, with the +$GOROOT/src/pkg/ prefix removed. +Outside the Go tree, you can use any TARG 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: myname/tree, myname/filter, etc. +Note that even if you keep your package source outside the +Go tree, running make install installs your +package binaries in the standard location—$GOROOT/pkg—to +make it easy to find them. +

+ +

+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 +for easy sorting. +

+ +

+If you create a new package directory in the Go tree, add it to the list in +$GOROOT/src/pkg/Makefile so that it +is included in the standard build. Then run: +

+cd $GOROOT/src/pkg
+./deps.bash
+
+

+to update the dependency file Make.deps. +(This happens automatically each time you run all.bash +or make.bash.) +

+ +

+If you change the imports of an existing package, +you do not need to edit $GOROOT/src/pkg/Makefile +but you will still need to run deps.bash as above. +

+ + +

Go source files

+ +

+The first statement in each of the source files listed in the Makefile +should be package name, where name +is the package's default name for imports. +(All files in a package must use the same name.) +Go's convention is that the package name is the last element of the +import path: the package imported as "crypto/rot13" +should be named rot13. +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. +

+ +

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

+ +

+Writing clean, idiomatic Go code is beyond the scope of this document. +Effective Go is an introduction to +that topic. +

+ +

Testing

+ +

+Go has a lightweight test framework known as gotest. +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 +and the testing package documentation give more detail. +

+ +

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

+ +

+To run the test, run either make test or gotest +(they are equivalent). +To run only the tests in a single test file, for instance one_test.go, +run gotest one_test.go. +

+ +

+If your change affects performance, add a Benchmark function +(see the gotest command documentation) +and run it using gotest -benchmarks=.. +

+ +

+Once your new code is tested and working, +it's time to get it reviewed and submitted. +

+ diff --git a/doc/contribute.html b/doc/contribute.html index 26451f56cf7..f15f4d2da51 100644 --- a/doc/contribute.html +++ b/doc/contribute.html @@ -3,175 +3,20 @@

Introduction

-This document explains how to write a new package, -how to test code, and how to contribute changes to the Go project. +This document explains how to contribute changes to the Go project. It assumes you have installed Go using the -installation instructions. (Note that -the gccgo frontend lives elsewhere; +installation instructions and +have written and tested your code. +(Note that the gccgo frontend lives elsewhere; see Contributing to gccgo.)

-

-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 mailing list -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. -

- -

Community resources

+

Testing redux

-For real-time help, there may be users or developers on -#go-nuts on the Freenode IRC server. -

- -

-The official mailing list for discussion of the Go language is -Go Nuts. -

- -

-Bugs can be reported using the Go issue tracker. -

- -

-For those who wish to keep up with development, -there is another mailing list, golang-checkins, -that receives a message summarizing each checkin to the Go repository. -

- - -

Creating a new package

- -

-The source code for the package with import path -x/y is, by convention, kept in the -directory $GOROOT/src/pkg/x/y. -

- -

Makefile

- -

-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 make. -Thus, the first file to create in a new package directory is -usually the Makefile. -The basic form is illustrated by src/pkg/container/vector/Makefile: -

- -
-include ../../../Make.$(GOARCH)
-
-TARG=container/vector
-GOFILES=\
-	intvector.go\
-	stringvector.go\
-	vector.go\
-
-include ../../../Make.pkg
-
- -

-The first and last lines include standard definitions and rules, -$(GOROOT)/src/Make.$(GOARCH) and $(GOROOT)/src/Make.pkg, -so that the body of the Makefile need only specify two variables. -For packages to be installed in the Go tree, use a relative path instead of -$(GOROOT)/src, so that make will work correctly even if $(GOROOT) contains spaces. -

- -

-TARG 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 Makefile appears, with the -$GOROOT/src/pkg/ removed. -

- -

-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 -for easy sorting. -

- -

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

-cd $GOROOT/src/pkg
-./deps.bash
-
-

-to update the dependency file Make.deps. -(This happens automatically each time you run all.bash -or make.bash.) -

- -

-If you change the imports of an existing package, -you do not need to edit $GOROOT/src/pkg/Makefile -but you will still need to run deps.bash as above. -

- - -

Go source files

- -

-The first statement in each of the source files listed in the Makefile -should be package name, where name -is the package's default name for imports. -(All files in a package must use the same name.) -Go's convention is that the package name is the last element of the -import path: the package imported as "crypto/rot13" -should be named rot13. -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. -

- -

-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. -

- -

-Writing clean, idiomatic Go code is beyond the scope of this document. -Effective Go is an introduction to -that topic. -

- -

Testing

- -

-Go has a lightweight test framework known as gotest. -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 -and the testing package documentation give more detail. -

- -

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

- -

-To run the test, run either make test or gotest -(they are equivalent). -To run only the tests in a single test file, for instance one_test.go, -run gotest one_test.go. -

- -

-Before sending code out for review, make sure everything -still works and the dependencies are right: +You've written and tested your code, but +before sending code out for review, run all the tests for the whole +tree to make sure the changes don't break other packages or programs: 

@@ -193,10 +38,6 @@ say “0 unexpected bugs” and must not
 add “test output differs.”
 

 
-

-Once your new code is tested and working,
-it's time to get it reviewed and submitted.
-

 
 
Code review

 
@@ -252,10 +93,15 @@ the Mercurial Queues extension.
 
 [extensions]
 codereview = YOUR_GO_ROOT/lib/codereview/codereview.py
+
+[ui]
+username = Your Name <you@server.dom>
 

 
 
Replace YOUR_GO_ROOT with the value of $GOROOT.
 The Mercurial configuration file format does not allow environment variable substitution.
+The username information will not be used unless
+you are a committer (see below), but Mercurial complains if it is missing.
 

 
 
Log in to the code review site.

@@ -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.
 (If you can use the account to
 sign in at google.com,
-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 Mercurial change log
+and in the CONTRIBUTORS file.
+You can create a Google Account
+associated with any address where you receive email.
 

 
 
@@ -369,7 +220,7 @@ After editing, the template might now read:
 # Lines beginning with # are ignored.
 # Multi-line values should be indented.
 
-Reviewer: r, rsc
+Reviewer: golang-dev@googlegroups.com
 CC: math-nuts@swtch.com
 
 Description:
@@ -475,7 +326,7 @@ might turn up:
 

 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
+so the correct answer might now be 9.  First, edit the section
 to remove the markers and leave the correct code:
 

 
@@ -486,15 +337,19 @@ to remove the markers and leave the correct code:
 

 
 

-then that is enough.  There is no need to inform Mercurial
-that you have corrected the file.
+Then ask Mercurial to mark the conflict as resolved:
 

 
+
+$ hg resolve -m flag_test.go
+

+
 

 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.
+changes, but you may still need to run
+hg resolve -m to mark the conflict resolved.
 

 
 
Mail the change for review

@@ -513,7 +368,7 @@ lines blank and then run:
 

 
 
-$ hg mail -r r,rsc --cc math-nuts@swtch.com 99999
+$ hg mail -r golang-dev@googlegroups.com --cc math-nuts@swtch.com 99999
 

 
 
to achieve the same effect.

@@ -580,7 +435,7 @@ will refuse the change:
 

 
 
-$ hg submit 12345678
+$ hg submit 99999
 local repository out of date; must sync before submit
 

 
@@ -609,56 +464,44 @@ when you next run hg sync.
 
 
 
-
The standard copyright header for files in the Go tree is:

+
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 Mercurial change log
+and in the CONTRIBUTORS file
+and perhaps the AUTHORS file.
+

+
+
The CONTRIBUTORS file
+defines who the Go contributors—the people—are;
+the AUTHORS file, which defines
+who “The Go Authors”—the copyright holders—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:
+

+
+

+This rigmarole needs to be done only for your first submission.
+

+
+
Code that you contribute should use the standard copyright header:

 
 
 // 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.
 

-
-

-Code you contribute should have this header.
-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
-AUTHORS file, which defines
-who “The Go Authors”—the copyright holders—are.
-

-
-

-When sending your first change list, you need to do two extra things before your
-code can be accepted.
-

-
    
-
  1. 
-If you are the copyright holder, you will need to agree to
-the individual
-contributor license agreement, which can be completed online;
-if your organization is the copyright holder, the organization
-will need to agree to the corporate contributor license agreement.
-(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.)
-
  2. 
-Send mail, or include information in the change list description,
-notifying us how you should be represented in the CONTRIBUTORS
-and AUTHORS 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 CONTRIBUTORS and, if
-appropriate, AUTHORS 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.

-

-This rigamarole needs to be done only for your first submission.
-

-
-

-Once the code is ready to be committed,
-one of the Go developers at Google will approve and submit
-your change.
-

diff --git a/lib/godoc/godoc.html b/lib/godoc/godoc.html
index 4f34c68a778..72ad1a5eaf1 100644
--- a/lib/godoc/godoc.html
+++ b/lib/godoc/godoc.html
@@ -91,6 +91,7 @@
     
  •  
    • 
     
  • How To
    • 
     
  • Install Go
    • 
+    
  • Write code
    • 
     
  • Contribute code
    • 
 
     
  •  
    •