From 5ff4c17907d5b19510a62e08fd8d3b11e62b431d Mon Sep 17 00:00:00 2001 From: Ondřej Surý Date: Tue, 13 Sep 2011 13:13:40 +0200 Subject: Imported Upstream version 60 --- doc/contribute.html | 529 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 529 insertions(+) create mode 100644 doc/contribute.html (limited to 'doc/contribute.html') diff --git a/doc/contribute.html b/doc/contribute.html new file mode 100644 index 000000000..c4b1ce2b5 --- /dev/null +++ b/doc/contribute.html @@ -0,0 +1,529 @@ + + +

Introduction

+ +

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

+ +

Discuss your design

+ +

+The project welcomes submissions but please let everyone know what +you're working on if you want it to become part of the main repository. +

+ +

+Before undertaking to write something new for the Go project, send +mail to the mailing +list to discuss what you plan to do. This gives everyone a +chance to validate the design, helps prevent duplication of effort, +and ensures that the idea fits inside the goals for the language +and tools. It also guarantees that the design is sound before code +is written; the code review tool is not the place for high-level +discussions. +

+ +

+In short, send mail before you code. +And don't start the discussion by mailing a change list! +

+ +

Testing redux

+ +

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

+ +
+cd $GOROOT/src
+./all.bash
+
+ +

+The final line printed by make all should be of the form: +

+ +
+N known bugs; 0 unexpected bugs
+
+ +

+The value of N varies over time, but the line must +say “0 unexpected bugs” and must not +add “test output differs.” +

+ + +

Code review

+ +

+Changes to Go must be reviewed before they are submitted, +no matter who makes the change. +(In exceptional cases, such as fixing a build, the review can +follow shortly after submitting.) +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. +

+ +

Caveat for Mercurial aficionados

+ +

+Using Mercurial with the code review extension is not the same +as using standard Mercurial. +

+ +

+The Go repository is maintained as a single line of reviewed changes; +we prefer to avoid the complexity of Mercurial's arbitrary change graph. +The code review extension helps here: its hg submit command +automatically checks for and warns about the local repository +being out of date compared to the remote one. +The hg submit command also verifies other +properties about the Go repository. +For example, +it checks that Go code being checked in is formatted in the standard style, +as defined by gofmt, +and it checks that the author of the code is properly recorded for +copyright purposes. +

+ +

+To help ensure changes are only created by hg submit, +the code review extension disables the standard hg commit +command. +

+ +

+Mercurial power users: if you prefer to use the Mercurial Queues extension, see +Using Mercurial Queues with Codereview. +

+ +

Configure the extension

+ +

Edit $GOROOT/.hg/hgrc to add:

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

+ +

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

+ +
+$ cd $GOROOT
+$ hg code-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
+
+ +

Configure your account settings.

+ +

Edit your code review settings. +Grab a nickname. +Many people prefer to set the Context option to +“Whole file” to see more context when reviewing changes. +

+ +

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, rsc is an alias for rsc@golang.org. +

+ +

Make a change

+ +

+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 +hg add, +hg rm, +hg cp, +or +hg mv. +

+ +

When you are ready to send a change out for review, run

+ +
+$ hg change
+
+ +

from any directory in your Go repository. +Mercurial will open a change description file in your editor. +(It uses the editor named by the $EDITOR environment variable, vi by default.) +The file will look like: +

+ +
+# Change list.
+# Lines beginning with # are ignored.
+# Multi-line values should be indented.
+
+Reviewer:
+CC:
+
+Description:
+	<enter description here>
+
+Files:
+	src/pkg/math/sin.go
+	src/pkg/math/tan.go
+	src/pkg/regexp/regexp.go
+
+ +

+The Reviewer line lists the reviewers assigned +to this change, and the CC line lists people to +notify about the change. +These can be code review nicknames or arbitrary email addresses. +Unless explicitly told otherwise, such as in the discussion leading +up to sending in the change list, set the +reviewer field to the +golang-dev@googlegroups.com +mailing list. +

+ +

+Replace “<enter description here>” +with a description of your change. +The first line of the change description is conventionally a one-line +summary of the change, prefixed by the primary affected package, +and is used as the subject for code review mail; the rest of the +description elaborates. +

+ +

+The Files 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 math +by deleting the line mentioning regexp.go. +

+ +

+After editing, the template might now read: +

+ +
+# Change list.
+# Lines beginning with # are ignored.
+# Multi-line values should be indented.
+
+Reviewer: golang-dev@googlegroups.com
+CC: math-nuts@swtch.com
+
+Description:
+	math: improved Sin, Cos and Tan 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
+
+ +

+The special sentence “Fixes issue 159.” associates +the change with issue 159 in the Go issue tracker. +When this change is eventually submitted, the issue +tracker will automatically mark the issue as fixed. +

+ +

+Save the file and exit the editor.

+ +

+The code review server assigns your change an issue number and URL, +which hg change will print, something like: +

+ +
+CL created: http://codereview.appspot.com/99999
+
+ +

+If you need to re-edit the change description, +run hg change 99999. +

+ +

+You can see a list of your pending changes by running hg pending (hg p for short). +

+ + +

Synchronize your client

+ +

While you were working, others might have submitted changes +to the repository. To update your client, run

+ +
+$ hg sync
+
+ +

(For Mercurial fans, hg sync runs hg pull -u +but then also synchronizes the local change list state against the new data.)

+ +

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

+ +

+For example, suppose you have edited flag_test.go but +someone else has committed an independent change. +When you run hg sync, you will get the (scary-looking) output +(emphasis added): + +

+$ 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.
+merging src/pkg/flag/flag_test.go failed!
+1 file updated, 0 files merged, 0 files removed, 1 file unresolved
+use 'hg resolve' to retry unresolved file merges
+$
+
+ +

+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 <<<<<<< and +>>>>>>>. +it is now your job to edit the file to combine them. +Continuing the example, searching for those strings in flag_test.go +might turn up: +

+ +
+	VisitAll(visitor);
+<<<<<<< local
+	if len(m) != 7 {
+=======
+	if len(m) != 8 {
+>>>>>>> other
+		t.Error("VisitAll misses some flags");
+
+ +

+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. First, edit the section +to remove the markers and leave the correct code: +

+ +
+	VisitAll(visitor);
+	if len(m) != 9 {
+		t.Error("VisitAll misses some flags");
+
+ +

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

+ +

Mail the change for review

+ +

To send out a change for review, run hg mail using the change list number +assigned during hg change:

+ +
+$ hg mail 99999
+
+ +

You can add to the Reviewer: and CC: lines +using the -r or --cc options. +In the above example, we could have left the Reviewer and CC +lines blank and then run: +

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

to achieve the same effect.

+ +

Note that -r and --cc cannot be spelled --r or -cc.

+ + +

Reviewing code

+ +

+Running hg mail 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. +

+ + +

Revise and upload

+ +

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 +

+ +
+$ hg mail 99999
+
+ +

again to upload the latest copy and send mail asking the reviewers to please take another look +(PTAL). +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. +

+

+The reviewer can comment on the new copy, and the process repeats. +The reviewer approves the change by replying with a mail that says +LGTM: looks good to me. +

+ +

Submit the change after the review

+ +

+After the code has been LGTM'ed, it is time to submit +it to the Mercurial repository. +If you are a committer, you can run: +

+ +
+$ hg submit 99999
+
+ +

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

+ +

+If your local copy of the repository is out of date, +hg submit +will refuse the change: +

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

+If you are not a committer, you cannot submit the change directly. +Instead, a committer, usually the reviewer who said LGTM, +will run: +

+ +
+$ hg clpatch 99999
+$ hg submit 99999
+
+ +

The clpatch 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 clpatch to try a change that +has been uploaded to the code review server.) +The submit 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 hg sync. +

+ + + + +

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