8
8
This document explains how to contribute changes to the Go project.
9
9
It assumes you have installed Go using the
10
<a href="/doc/install">installation instructions</a> and
10
<a href="/doc/install/source">installation instructions</a> and
11
11
have <a href="code.html">written and tested your code</a>.
12
12
(Note that the <code>gccgo</code> frontend lives elsewhere;
13
13
see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
53
The final line printed by <code>make all</code> should be of the form:
57
<i>N</i> known bugs; 0 unexpected bugs
61
The value of <i>N</i> varies over time, but the line must
62
say “<code>0 unexpected bugs</code>” and must not
63
add “<code>test output differs</code>.”
49
./all.bash # On Windows, run all.bat
53
After running for a while, the command should print "<code>ALL TESTS PASSED</code>".
67
56
<h2 id="Code_review">Code review</h2>
108
Mercurial power users: if you prefer to use the Mercurial Queues extension, see
109
<a href="codereview_with_mq.html">Using Mercurial Queues with Codereview</a>.
112
96
<h3>Configure the extension</h3>
114
98
<p>Edit <code>$GOROOT/.hg/hgrc</code> to add:</p>
118
codereview = YOUR_GO_ROOT/lib/codereview/codereview.py
102
codereview = $GOROOT/lib/codereview/codereview.py
121
105
username = Your Name <you@server.dom>
124
<p>Replace YOUR_GO_ROOT with the value of <code>$GOROOT</code>.
125
The Mercurial configuration file format does not allow environment variable substitution.
126
109
The <code>username</code> information will not be used unless
127
110
you are a committer (see below), but Mercurial complains if it is missing.
114
After adding the extension, <code>hg help codereview</code>
115
will show documentation for its commands. As the codereview extension is only
116
enabled for your checkout in <code>$GOROOT</code>, the remainder of this
117
document assumes you are inside <code>$GOROOT</code> when issuing commands.
121
Windows users may need to perform extra steps to get the code review
122
extension working. See the
123
<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a>
124
on the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for details.
130
127
<h3>Log in to the code review site.</h3>
133
130
The code review server uses a Google Account to authenticate.
134
131
(If you can use the account to
135
132
<a href="https://www.google.com/accounts/Login?hl=en&continue=http://www.google.com/">sign in at google.com</a>,
136
you can use it to sign in to the code review server.
133
you can use it to sign in to the code review server.)
137
134
The email address you use on the Code Review site
138
135
will be recorded in the <a href="http://code.google.com/p/go/source/list">Mercurial change log</a>
139
136
and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file.
140
137
You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a>
141
138
associated with any address where you receive email.
139
If you've enabled the two-step verification feature, don't forget to generate an
140
application-specific password and use that when prompted for a password.
163
162
For example, <code>rsc</code> is an alias for <code>rsc@golang.org</code>.
165
<h3>Switch to the default branch</h3>
168
Most Go installations use a release branch, but new changes should
169
only be made to the default branch. (They may be applied later to a release
170
branch as part of the release process.)
171
Before making a change, make sure you use the default branch:
166
178
<h3>Make a change</h3>
263
275
the change with issue 159 in the <a href="http://code.google.com/p/go/issues/list">Go issue tracker</a>.
264
276
When this change is eventually submitted, the issue
265
277
tracker will automatically mark the issue as fixed.
278
(These conventions are described in detail by the
279
<a href="http://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control">Google Project Hosting Issue Tracker documentation</a>.)
277
291
CL created: http://codereview.appspot.com/99999
294
<h3>Adding or removing files from an existing change</h3>
281
If you need to re-edit the change description,
297
If you need to re-edit the change description, or change the files included in the CL,
282
298
run <code>hg change 99999</code>.
286
You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short).
302
Alternatively, you can use
306
$ hg file 99999 somefile
310
to add <code>somefile</code> to CL 99999, and
314
$ hg file -d 99999 somefile
318
to remove <code>somefile</code> from the CL.
322
A file may only belong to a single active CL at a time. <code>hg file</code>
323
will issue a warning if a file is moved between changes.
290
326
<h3>Synchronize your client</h3>
379
415
<h3>Mail the change for review</h3>
418
Creating or uploading the change uploads a copy of the diff to the code review server,
419
but it does not notify anyone about it. To do that, you need to run <code>hg mail</code>
381
423
<p>To send out a change for review, run <code>hg mail</code> using the change list number
382
424
assigned during <code>hg change</code>:</p>
400
442
<p>Note that <code>-r</code> and <code>--cc</code> cannot be spelled <code>--r</code> or <code>-cc</code>.</p>
445
If your change relates to an open issue, please add a comment to the issue
446
announcing your proposed fix, including a link to your CL.
403
449
<h3>Reviewing code</h3>
413
459
<h3>Revise and upload</h3>
415
<p>You will probably revise your code in response to the reviewer comments.
462
You will probably revise your code in response to the reviewer comments. When
463
you have done this, you can upload your change to the code review server
464
without sending a notification by running <code>hg upload</code> using the change
465
list number assigned during <code>hg change</code>
416
473
When you have revised the code and are ready for another round of review, run
433
490
<code>LGTM</code>: looks good to me.
494
You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short).
497
<h3>Reviewing code by others</h3>
500
You can import a CL proposed by someone else into your local Mercurial client
501
by using the <code>hg clpatch</code> command. Running
509
will apply the latest diff for CL 99999 to your working copy. If any of the
510
files referenced in CL 99999 have local modifications, <code>clpatch</code>
511
will refuse to apply the whole diff. Once applied, CL 99999 will show up in
512
the output of <code>hg pending</code> and others.
516
To revert a CL you have applied locally, use the <code>hg revert</code>
525
will revert any files mentioned on CL 99999 to their original state. This can
526
be an effective way of reverting one CL revision and applying another.
530
Once the CL has been submitted, the next time you run <code>hg sync</code>
531
it will be removed from your local pending list. Occasionally the pending list
532
can get out of sync leaving stale references to closed or abandoned CLs.
533
You can use <code>hg change -D 99999</code> to remove the reference to CL 99999.
436
536
<h3>Submit the change after the review</h3>
439
539
After the code has been <code>LGTM</code>'ed, it is time to submit
440
540
it to the Mercurial repository.
544
If you are not a committer, you cannot submit the change directly.
545
Instead a committer, usually the reviewer who said <code>LGTM</code>,
555
The <code>submit</code> command submits the code. You will be listed as the
556
author, but the change message will also indicate who the committer was.
557
Your local client will notice that the change has been submitted
558
when you next run <code>hg sync</code>.
441
562
If you are a committer, you can run:
463
583
local repository out of date; must sync before submit
467
If you are not a committer, you cannot submit the change directly.
468
Instead, a committer, usually the reviewer who said <code>LGTM</code>,
477
<p>The <code>clpatch</code> command imports your change 99999 into
478
the committer's local Mercurial client, at which point the committer
479
can check or test the code more.
480
(Anyone can run <code>clpatch</code> to try a change that
481
has been uploaded to the code review server.)
482
The <code>submit</code> command submits the code. You will be listed as the
483
author, but the change message will also indicate who the committer was.
484
Your local client will notice that the change has been submitted
485
when you next run <code>hg sync</code>.
489
<h3 id="copyright">Copyright</h3>
586
<h2 id="copyright">Copyright</h2>
491
588
<p>Files in the Go repository don't list author names,
492
589
both to avoid clutter and to avoid having to keep the lists up to date.
498
595
<p>The <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file
499
596
defines who the Go contributors—the people—are;
500
the <a href="/AUTHORS"><code>AUTHORS</code></a> file, which defines
597
the <a href="/AUTHORS"><code>AUTHORS</code></a> file defines
501
598
who “The Go Authors”—the copyright holders—are.
502
599
The Go developers at Google will update these files when submitting
503
600
your first change.
525
622
<p>Code that you contribute should use the standard copyright header:</p>
528
// Copyright 2012 The Go Authors. All rights reserved.
625
// Copyright 2013 The Go Authors. All rights reserved.
529
626
// Use of this source code is governed by a BSD-style
530
627
// license that can be found in the LICENSE file.
631
Files in the repository are copyright the year they are added. It is not
632
necessary to update the copyright year on files that you change.
added
removed
doc/contribute.html
