From 10650b718e9020238b9db8ebdb34f674189709c5 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 9 Dec 2009 14:05:12 -0800 Subject: doc: split contribute.html into code.html and contribute.html R=r http://codereview.appspot.com/170042 --- doc/contribute.html | 275 +++++++++++----------------------------------------- 1 file changed, 59 insertions(+), 216 deletions(-) (limited to 'doc/contribute.html') diff --git a/doc/contribute.html b/doc/contribute.html index 26451f56c..f15f4d2da 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

- -

-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

+

Testing redux

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

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

 
-

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

-
    
+
    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:
+
      
 
    • 
 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
+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.)
-
    • 
-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.
+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.
+

-- 
cgit v1.2.3