"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/contribute.html" (9 Sep 2020, 37051 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!--{
    2     "Title": "Contribution Guide"
    3 }-->
    5 <p>
    6 The Go project welcomes all contributors.
    7 </p>
    9 <p>
   10 This document is a guide to help you through the process
   11 of contributing to the Go project, which is a little different
   12 from that used by other open source projects.
   13 We assume you have a basic understanding of Git and Go.
   14 </p>
   16 <p>
   17 In addition to the information here, the Go community maintains a
   18 <a href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page.
   19 Feel free to contribute to the wiki as you learn the review process.
   20 </p>
   22 <p>
   23 Note that the <code>gccgo</code> front end lives elsewhere;
   24 see <a href="gccgo_contribute.html">Contributing to gccgo</a>.
   25 </p>
   27 <h2 id="contributor">Becoming a contributor</h2>
   29 <h3 id="contrib_overview">Overview</h3>
   31 <p>
   32 The first step is registering as a Go contributor and configuring your environment.
   33 Here is a checklist of the required steps to follow:
   34 </p>
   36 <ul>
   37 <li>
   38 <b>Step 0</b>: Decide on a single Google Account you will be using to contribute to Go.
   39 Use that account for all the following steps and make sure that <code>git</code>
   40 is configured to create commits with that account's e-mail address.
   41 </li>
   42 <li>
   43 <b>Step 1</b>: <a href="https://cla.developers.google.com/clas">Sign and submit</a> a
   44 CLA (Contributor License Agreement).
   45 </li>
   46 <li>
   47 <b>Step 2</b>: Configure authentication credentials for the Go Git repository.
   48 Visit <a href="https://go.googlesource.com/">go.googlesource.com</a>, click
   49 on the gear icon (top right), then on "Obtain password", and follow the
   50 instructions.
   51 </li>
   52 <li>
   53 <b>Step 3</b>: Register for Gerrit, the code review tool used by the Go team,
   54 by <a href="https://go-review.googlesource.com/login/">visiting this page</a>.
   55 The CLA and the registration need to be done only once for your account.
   56 </li>
   57 <li>
   58 <b>Step 4</b>: Install <code>git-codereview</code> by running
   59 <code>go get -u golang.org/x/review/git-codereview</code>
   60 </li>
   61 </ul>
   63 <p>
   64 If you prefer, there is an automated tool that walks through these steps.
   65 Just run:
   66 </p>
   68 <pre>
   69 $ go get -u golang.org/x/tools/cmd/go-contrib-init
   70 $ cd /code/to/edit
   71 $ go-contrib-init
   72 </pre>
   74 <p>
   75 The rest of this chapter elaborates on these instructions.
   76 If you have completed the steps above (either manually or through the tool), jump to
   77 <a href="#before_contributing">Before contributing code</a>.
   78 </p>
   80 <h3 id="google_account">Step 0: Select a Google Account</h3>
   82 <p>
   83 A contribution to Go is made through a Google account with a specific
   84 e-mail address.
   85 Make sure to use the same account throughout the process and
   86 for all your subsequent contributions.
   87 You may need to decide whether to use a personal address or a corporate address.
   88 The choice will depend on who
   89 will own the copyright for the code that you will be writing
   90 and submitting.
   91 You might want to discuss this topic with your employer before deciding which
   92 account to use.
   93 </p>
   95 <p>
   96 Google accounts can either be Gmail e-mail accounts, G Suite organization accounts, or
   97 accounts associated with an external e-mail address.
   98 For instance, if you need to use
   99 an existing corporate e-mail that is not managed through G Suite, you can create
  100 an account associated
  101 <a href="https://accounts.google.com/SignUpWithoutGmail">with your existing
  102 e-mail address</a>.
  103 </p>
  105 <p>
  106 You also need to make sure that your Git tool is configured to create commits
  107 using your chosen e-mail address.
  108 You can either configure Git globally
  109 (as a default for all projects), or locally (for a single specific project).
  110 You can check the current configuration with this command:
  111 </p>
  113 <pre>
  114 $ git config --global user.email  # check current global config
  115 $ git config user.email           # check current local config
  116 </pre>
  118 <p>
  119 To change the configured address:
  120 </p>
  122 <pre>
  123 $ git config --global user.email name@example.com   # change global config
  124 $ git config user.email name@example.com            # change local config
  125 </pre>
  128 <h3 id="cla">Step 1: Contributor License Agreement</h3>
  130 <p>
  131 Before sending your first change to the Go project
  132 you must have completed one of the following two CLAs.
  133 Which CLA you should sign depends on who owns the copyright to your work.
  134 </p>
  136 <ul>
  137 <li>
  138 If you are the copyright holder, you will need to agree to the
  139 <a href="https://developers.google.com/open-source/cla/individual">individual
  140 contributor license agreement</a>, which can be completed online.
  141 </li>
  142 <li>
  143 If your organization is the copyright holder, the organization
  144 will need to agree to the
  145 <a href="https://developers.google.com/open-source/cla/corporate">corporate
  146 contributor license agreement</a>.<br>
  147 </li>
  148 </ul>
  150 <p>
  151 You can check your currently signed agreements and sign new ones at
  152 the <a href="https://cla.developers.google.com/clas?pli=1&amp;authuser=1">Google Developers
  153 Contributor License Agreements</a> website.
  154 If the copyright holder for your contribution has already completed the
  155 agreement in connection with another Google open source project,
  156 it does not need to be completed again.
  157 </p>
  159 <p>
  160 If the copyright holder for the code you are submitting changes&mdash;for example,
  161 if you start contributing code on behalf of a new company&mdash;please send mail
  162 to the <a href="mailto:golang-dev@googlegroups.com"><code>golang-dev</code>
  163 mailing list</a>.
  164 This will let us know the situation so we can make sure an appropriate agreement is
  165 completed and update the <code>AUTHORS</code> file.
  166 </p>
  169 <h3 id="config_git_auth">Step 2: Configure git authentication</h3>
  171 <p>
  172 The main Go repository is located at
  173 <a href="https://go.googlesource.com">go.googlesource.com</a>,
  174 a Git server hosted by Google.
  175 Authentication on the web server is made through your Google account, but
  176 you also need to configure <code>git</code> on your computer to access it.
  177 Follow this steps:
  178 </p>
  180 <ol>
  181 <li>
  182 Visit <a href="https://go.googlesource.com">go.googlesource.com</a>
  183 and click on "Generate Password" in the page's top right menu bar.
  184 You will be redirected to accounts.google.com to sign in.
  185 </li>
  186 <li>
  187 After signing in, you will be taken to a page with the title "Configure Git".
  188 This page contains a personalized script that when run locally will configure Git
  189 to hold your unique authentication key.
  190 This key is paired with one that is generated and stored on the server,
  191 analogous to how SSH keys work.
  192 </li>
  193 <li>
  194 Copy and run this script locally in your terminal to store your secret
  195 authentication token in a <code>.gitcookies</code> file.
  196 If you are using a Windows computer and running <code>cmd</code>,
  197 you should instead follow the instructions in the yellow box to run the command;
  198 otherwise run the regular script.
  199 </li>
  200 </ol>
  202 <h3 id="auth">Step 3: Create a Gerrit account </h3>
  204 <p>
  205 Gerrit is an open-source tool used by Go maintainers to discuss and review
  206 code submissions.
  207 </p>
  209 <p>
  210 To register your account, visit <a href="https://go-review.googlesource.com/login/">
  211 go-review.googlesource.com/login/</a> and sign in once using the same Google Account you used above.
  212 </p>
  214 <h3 id="git-codereview_install">Step 4: Install the git-codereview command</h3>
  216 <p>
  217 Changes to Go must be reviewed before they are accepted, no matter who makes the change.
  218 A custom <code>git</code> command called <code>git-codereview</code>
  219 simplifies sending changes to Gerrit.
  220 </p>
  222 <p>
  223 Install the <code>git-codereview</code> command by running,
  224 </p>
  226 <pre>
  227 $ go get -u golang.org/x/review/git-codereview
  228 </pre>
  230 <p>
  231 Make sure <code>git-codereview</code> is installed in your shell path, so that the
  232 <code>git</code> command can find it.
  233 Check that
  234 </p>
  236 <pre>
  237 $ git codereview help
  238 </pre>
  240 <p>
  241 prints help text, not an error. If it prints an error, make sure that
  242 <code>$GOPATH/bin</code> is in your <code>$PATH</code>.
  243 </p>
  245 <p>
  246 On Windows, when using git-bash you must make sure that
  247 <code>git-codereview.exe</code> is in your <code>git</code> exec-path.
  248 Run <code>git --exec-path</code> to discover the right location then create a
  249 symbolic link or just copy the executable from <code>$GOPATH/bin</code> to this
  250 directory.
  251 </p>
  254 <h2 id="before_contributing">Before contributing code</h2>
  256 <p>
  257 The project welcomes code patches, but to make sure things are well
  258 coordinated you should discuss any significant change before starting
  259 the work.
  260 It's recommended that you signal your intention to contribute in the
  261 issue tracker, either by <a href="https://golang.org/issue/new">filing
  262 a new issue</a> or by claiming
  263 an <a href="https://golang.org/issues">existing one</a>.
  264 </p>
  266 <h3 id="check_tracker">Check the issue tracker</h3>
  268 <p>
  269 Whether you already know what contribution to make, or you are searching for
  270 an idea, the <a href="https://github.com/golang/go/issues">issue tracker</a> is
  271 always the first place to go.
  272 Issues are triaged to categorize them and manage the workflow.
  273 </p>
  275 <p>
  276 Most issues will be marked with one of the following workflow labels:
  277 </p>
  279 <ul>
  280     <li>
  281     <b>NeedsInvestigation</b>: The issue is not fully understood
  282     and requires analysis to understand the root cause.
  283     </li>
  284     <li>
  285     <b>NeedsDecision</b>: the issue is relatively well understood, but the
  286     Go team hasn't yet decided the best way to address it.
  287     It would be better to wait for a decision before writing code.
  288     If you are interested on working on an issue in this state,
  289     feel free to "ping" maintainers in the issue's comments
  290     if some time has passed without a decision.
  291     </li>
  292     <li>
  293     <b>NeedsFix</b>: the issue is fully understood and code can be written
  294     to fix it.
  295     </li>
  296 </ul>
  298 <p>
  299 You can use GitHub's search functionality to find issues to help out with. Examples:
  300 </p>
  302 <ul>
  303     <li>
  304     Issues that need investigation: <a href="https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation"><code>is:issue is:open label:NeedsInvestigation</code></a>
  305     </li>
  306     <li>
  307     Issues that need a fix: <a href="https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix"><code>is:issue is:open label:NeedsFix</code></a>
  308     </li>
  309     <li>
  310     Issues that need a fix and have a CL: <a href="https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix "golang.org/cl"</code></a>
  311     </li>
  312     <li>
  313     Issues that need a fix and do not have a CL: <a href="https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix NOT "golang.org/cl"</code></a>
  314     </li>
  315 </ul>
  317 <h3 id="design">Open an issue for any new problem</h3>
  319 <p>
  320 Excluding very trivial changes, all contributions should be connected
  321 to an existing issue.
  322 Feel free to open one and discuss your plans.
  323 This process gives everyone a chance to validate the design,
  324 helps prevent duplication of effort,
  325 and ensures that the idea fits inside the goals for the language and tools.
  326 It also checks that the design is sound before code is written;
  327 the code review tool is not the place for high-level discussions.
  328 </p>
  330 <p>
  331 When planning work, please note that the Go project follows a <a
  332 href="https://golang.org/wiki/Go-Release-Cycle">six-month development cycle</a>.
  333 The latter half of each cycle is a three-month feature freeze during
  334 which only bug fixes and documentation updates are accepted.
  335 New contributions can be sent during a feature freeze, but they will
  336 not be merged until the freeze is over.
  337 </p>
  339 <p>
  340 Significant changes to the language, libraries, or tools must go
  341 through the
  342 <a href="https://golang.org/s/proposal-process">change proposal process</a>
  343 before they can be accepted.
  344 </p>
  346 <p>
  347 Sensitive security-related issues (only!) should be reported to <a href="mailto:security@golang.org">security@golang.org</a>.
  348 </p>
  350 <h2 id="sending_a_change_github">Sending a change via GitHub</h2>
  352 <p>
  353 First-time contributors that are already familiar with the
  354 <a href="https://guides.github.com/introduction/flow/">GitHub flow</a>
  355 are encouraged to use the same process for Go contributions.
  356 Even though Go
  357 maintainers use Gerrit for code review, a bot called Gopherbot has been created to sync
  358 GitHub pull requests to Gerrit.
  359 </p>
  361 <p>
  362 Open a pull request as you normally would.
  363 Gopherbot will create a corresponding Gerrit change and post a link to
  364 it on your GitHub pull request; updates to the pull request will also
  365 get reflected in the Gerrit change.
  366 When somebody comments on the change, their comment will be also
  367 posted in your pull request, so you will get a notification.
  368 </p>
  370 <p>
  371 Some things to keep in mind:
  372 </p>
  374 <ul>
  375 <li>
  376 To update the pull request with new code, just push it to the branch; you can either
  377 add more commits, or rebase and force-push (both styles are accepted).
  378 </li>
  379 <li>
  380 If the request is accepted, all commits will be squashed, and the final
  381 commit description will be composed by concatenating the pull request's
  382 title and description.
  383 The individual commits' descriptions will be discarded.
  384 See <a href="#commit_messages">Writing good commit messages</a> for some
  385 suggestions.
  386 </li>
  387 <li>
  388 Gopherbot is unable to sync line-by-line codereview into GitHub: only the
  389 contents of the overall comment on the request will be synced.
  390 Remember you can always visit Gerrit to see the fine-grained review.
  391 </li>
  392 </ul>
  394 <h2 id="sending_a_change_gerrit">Sending a change via Gerrit</h2>
  396 <p>
  397 It is not possible to fully sync Gerrit and GitHub, at least at the moment,
  398 so we recommend learning Gerrit.
  399 It's different but powerful and familiarity with it will help you understand
  400 the flow.
  401 </p>
  403 <h3 id="gerrit_overview">Overview</h3>
  405 <p>
  406 This is an overview of the overall process:
  407 </p>
  409 <ul>
  410 <li>
  411 <b>Step 1:</b> Clone the Go source code from <code>go.googlesource.com</code>
  412 and make sure it's stable by compiling and testing it once:
  413 <pre>
  414 $ git clone https://go.googlesource.com/go
  415 $ cd go/src
  416 $ ./all.bash                                # compile and test
  417 </pre>
  418 </li>
  420 <li>
  421 <b>Step 2:</b> Prepare changes in a new branch, created from the master branch.
  422 To commit the changes, use <code>git</code> <code>codereview</code> <code>change</code>; that
  423 will create or amend a single commit in the branch.
  424 <pre>
  425 $ git checkout -b mybranch
  426 $ [edit files...]
  427 $ git add [files...]
  428 $ git codereview change   # create commit in the branch
  429 $ [edit again...]
  430 $ git add [files...]
  431 $ git codereview change   # amend the existing commit with new changes
  432 $ [etc.]
  433 </pre>
  434 </li>
  436 <li>
  437 <b>Step 3:</b> Test your changes, re-running <code>all.bash</code>.
  438 <pre>
  439 $ ./all.bash    # recompile and test
  440 </pre>
  441 </li>
  443 <li>
  444 <b>Step 4:</b> Send the changes for review to Gerrit using <code>git</code>
  445 <code>codereview</code> <code>mail</code> (which doesn't use e-mail, despite the name).
  446 <pre>
  447 $ git codereview mail     # send changes to Gerrit
  448 </pre>
  449 </li>
  451 <li>
  452 <b>Step 5:</b> After a review, apply changes to the same single commit
  453 and mail them to Gerrit again:
  454 <pre>
  455 $ [edit files...]
  456 $ git add [files...]
  457 $ git codereview change   # update same commit
  458 $ git codereview mail     # send to Gerrit again
  459 </pre>
  460 </li>
  461 </ul>
  463 <p>
  464 The rest of this section describes these steps in more detail.
  465 </p>
  468 <h3 id="checkout_go">Step 1: Clone the Go source code</h3>
  470 <p>
  471 In addition to a recent Go installation, you need to have a local copy of the source
  472 checked out from the correct repository.
  473 You can check out the Go source repo onto your local file system anywhere
  474 you want as long as it's outside your <code>GOPATH</code>.
  475 Clone from <code>go.googlesource.com</code> (not GitHub):
  476 </p>
  478 <pre>
  479 $ git clone https://go.googlesource.com/go
  480 $ cd go
  481 </pre>
  483 <h3 id="make_branch">Step 2: Prepare changes in a new branch</h3>
  485 <p>
  486 Each Go change must be made in a separate branch, created from the master branch.
  487 You can use
  488 the normal <code>git</code> commands to create a branch and add changes to the
  489 staging area:
  490 </p>
  492 <pre>
  493 $ git checkout -b mybranch
  494 $ [edit files...]
  495 $ git add [files...]
  496 </pre>
  498 <p>
  499 To commit changes, instead of <code>git commit</code>, use <code>git codereview change</code>.
  500 </p>
  502 <pre>
  503 $ git codereview change
  504 (open $EDITOR)
  505 </pre>
  507 <p>
  508 You can edit the commit description in your favorite editor as usual.
  509 The  <code>git</code> <code>codereview</code> <code>change</code> command
  510 will automatically add a unique Change-Id line near the bottom.
  511 That line is used by Gerrit to match successive uploads of the same change.
  512 Do not edit or delete it.
  513 A Change-Id looks like this:
  514 </p>
  516 <pre>
  517 Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990
  518 </pre>
  520 <p>
  521 The tool also checks that you've
  522 run <code>go</code> <code>fmt</code> over the source code, and that
  523 the commit message follows the <a href="#commit_messages">suggested format</a>.
  524 </p>
  526 <p>
  527 If you need to edit the files again, you can stage the new changes and
  528 re-run <code>git</code> <code>codereview</code> <code>change</code>: each subsequent
  529 run will amend the existing commit while preserving the Change-Id.
  530 </p>
  532 <p>
  533 Make sure that you always keep a single commit in each branch.
  534 If you add more
  535 commits by mistake, you can use <code>git</code> <code>rebase</code> to
  536 <a href="https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github">squash them together</a>
  537 into a single one.
  538 </p>
  541 <h3 id="testing">Step 3: Test your changes</h3>
  543 <p>
  544 You've <a href="code.html">written and tested your code</a>, but
  545 before sending code out for review, run <i>all the tests for the whole
  546 tree</i> to make sure the changes don't break other packages or programs:
  547 </p>
  549 <pre>
  550 $ cd go/src
  551 $ ./all.bash
  552 </pre>
  554 <p>
  555 (To build under Windows use <code>all.bat</code>; this also requires
  556 setting the environment variable <code>GOROOT_BOOTSTRAP</code> to the
  557 directory holding the Go tree for the bootstrap compiler.)
  558 </p>
  560 <p>
  561 After running for a while and printing a lot of testing output, the command should finish
  562 by printing,
  563 </p>
  565 <pre>
  567 </pre>
  569 <p>
  570 You can use <code>make.bash</code> instead of <code>all.bash</code>
  571 to just build the compiler and the standard library without running the test suite.
  572 Once the <code>go</code> tool is built, it will be installed as <code>bin/go</code>
  573 under the directory in which you cloned the Go repository, and you can
  574 run it directly from there.
  575 See also
  576 the section on how to <a href="#quick_test">test your changes quickly</a>.
  577 </p>
  579 <h3 id="mail">Step 4: Send changes for review</h3>
  581 <p>
  582 Once the change is ready and tested over the whole tree, send it for review.
  583 This is done with the <code>mail</code> sub-command which, despite its name, doesn't
  584 directly mail anything; it just sends the change to Gerrit:
  585 </p>
  587 <pre>
  588 $ git codereview mail
  589 </pre>
  591 <p>
  592 Gerrit assigns your change a number and URL, which <code>git</code> <code>codereview</code> <code>mail</code> will print, something like:
  593 </p>
  595 <pre>
  596 remote: New Changes:
  597 remote:   https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments
  598 </pre>
  600 <p>
  601 If you get an error instead, check the
  602 <a href="#troubleshooting_mail">Troubleshooting mail errors</a> section.
  603 </p>
  605 <p>
  606 If your change relates to an open GitHub issue and you have followed the <a href="#commit_messages">
  607 suggested commit message format</a>, the issue will be updated in a few minutes by a bot,
  608 linking your Gerrit change to it in the comments.
  609 </p>
  612 <h3 id="revise">Step 5: Revise changes after a review</h3>
  614 <p>
  615 Go maintainers will review your code on Gerrit, and you will get notifications via e-mail.
  616 You can see the review on Gerrit and comment on them there.
  617 You can also reply
  618 <a href="https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email">using e-mail</a>
  619 if you prefer.
  620 </p>
  622 <p>
  623 If you need to revise your change after the review, edit the files in
  624 the same branch you previously created, add them to the Git staging
  625 area, and then amend the commit with
  626 <code>git</code> <code>codereview</code> <code>change</code>:
  627 </p>
  629 <pre>
  630 $ git codereview change     # amend current commit
  631 (open $EDITOR)
  632 $ git codereview mail       # send new changes to Gerrit
  633 </pre>
  635 <p>
  636 If you don't need to change the commit description, just save and exit from the editor.
  637 Remember not to touch the special Change-Id line.
  638 </p>
  640 <p>
  641 Again, make sure that you always keep a single commit in each branch.
  642 If you add more
  643 commits by mistake, you can use <code>git rebase</code> to
  644 <a href="https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github">squash them together</a>
  645 into a single one.
  646 </p>
  648 <h2 id="commit_messages">Good commit messages</h2>
  650 <p>
  651 Commit messages in Go follow a specific set of conventions,
  652 which we discuss in this section.
  653 </p>
  655 <p>
  656 Here is an example of a good one:
  657 </p>
  659 <pre>
  660 math: improve Sin, Cos and Tan precision for very large arguments
  662 The existing implementation has poor numerical properties for
  663 large arguments, so use the McGillicutty algorithm to improve
  664 accuracy above 1e10.
  666 The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm
  668 Fixes #159
  669 </pre>
  671 <h3 id="first_line">First line</h3>
  673 <p>
  674 The first line of the change description is conventionally a short one-line
  675 summary of the change, prefixed by the primary affected package.
  676 </p>
  678 <p>
  679 A rule of thumb is that it should be written so to complete the sentence
  680 "This change modifies Go to _____."
  681 That means it does not start with a capital letter, is not a complete sentence,
  682 and actually summarizes the result of the change.
  683 </p>
  685 <p>
  686 Follow the first line by a blank line.
  687 </p>
  689 <h3 id="main_content">Main content</h3>
  691 <p>
  692 The rest of the description elaborates and should provide context for the
  693 change and explain what it does.
  694 Write in complete sentences with correct punctuation, just like
  695 for your comments in Go.
  696 Don't use HTML, Markdown, or any other markup language.
  697 </p>
  699 <p>
  700 Add any relevant information, such as benchmark data if the change
  701 affects performance.
  702 The <a href="https://godoc.org/golang.org/x/perf/cmd/benchstat">benchstat</a>
  703 tool is conventionally used to format
  704 benchmark data for change descriptions.
  705 </p>
  707 <h3 id="ref_issues">Referencing issues</h3>
  709 <p>
  710 The special notation "Fixes #12345" associates the change with issue 12345 in the
  711 <a href="https://golang.org/issue/12345">Go issue tracker</a>.
  712 When this change is eventually applied, the issue
  713 tracker will automatically mark the issue as fixed.
  714 </p>
  716 <p>
  717 If the change is a partial step towards the resolution of the issue,
  718 uses the notation "Updates #12345".
  719 This will leave a comment in the issue
  720 linking back to the change in Gerrit, but it will not close the issue
  721 when the change is applied.
  722 </p>
  724 <p>
  725 If you are sending a change against a subrepository, you must use
  726 the fully-qualified syntax supported by GitHub to make sure the change is
  727 linked to the issue in the main repository, not the subrepository.
  728 All issues are tracked in the main repository's issue tracker.
  729 The correct form is "Fixes golang/go#159".
  730 </p>
  733 <h2 id="review">The review process</h2>
  735 <p>
  736 This section explains the review process in detail and how to approach
  737 reviews after a change has been mailed.
  738 </p>
  741 <h3 id="mistakes">Common beginner mistakes</h3>
  743 <p>
  744 When a change is sent to Gerrit, it is usually triaged within a few days.
  745 A maintainer will have a look and provide some initial review that for first-time
  746 contributors usually focuses on basic cosmetics and common mistakes.
  747 These include things like:
  748 </p>
  750 <ul>
  751 <li>
  752 Commit message not following the <a href="#commit_messages">suggested
  753 format</a>.
  754 </li>
  756 <li>
  757 The lack of a linked GitHub issue.
  758 The vast majority of changes
  759 require a linked issue that describes the bug or the feature that the change
  760 fixes or implements, and consensus should have been reached on the tracker
  761 before proceeding with it.
  762 Gerrit reviews do not discuss the merit of the change,
  763 just its implementation.
  764 <br>
  765 Only trivial or cosmetic changes will be accepted without an associated issue.
  766 </li>
  768 <li>
  769 Change sent during the freeze phase of the development cycle, when the tree
  770 is closed for general changes.
  771 In this case,
  772 a maintainer might review the code with a line such as <code>R=go1.12</code>,
  773 which means that it will be reviewed later when the tree opens for a new
  774 development window.
  775 You can add <code>R=go1.XX</code> as a comment yourself
  776 if you know that it's not the correct time frame for the change.
  777 </li>
  778 </ul>
  780 <h3 id="trybots">Trybots</h3>
  782 <p>
  783 After an initial reading of your change, maintainers will trigger trybots,
  784 a cluster of servers that will run the full test suite on several different
  785 architectures.
  786 Most trybots complete in a few minutes, at which point a link will
  787 be posted in Gerrit where you can see the results.
  788 </p>
  790 <p>
  791 If the trybot run fails, follow the link and check the full logs of the
  792 platforms on which the tests failed.
  793 Try to understand what broke, update your patch to fix it, and upload again.
  794 Maintainers will trigger a new trybot run to see
  795 if the problem was fixed.
  796 </p>
  798 <p>
  799 Sometimes, the tree can be broken on some platforms for a few hours; if
  800 the failure reported by the trybot doesn't seem related to your patch, go to the
  801 <a href="https://build.golang.org">Build Dashboard</a> and check if the same
  802 failure appears in other recent commits on the same platform.
  803 In this case,
  804 feel free to write a comment in Gerrit to mention that the failure is
  805 unrelated to your change, to help maintainers understand the situation.
  806 </p>
  808 <h3 id="reviews">Reviews</h3>
  810 <p>
  811 The Go community values very thorough reviews.
  812 Think of each review comment like a ticket: you are expected to somehow "close" it
  813 by acting on it, either by implementing the suggestion or convincing the
  814 reviewer otherwise.
  815 </p>
  817 <p>
  818 After you update the change, go through the review comments and make sure
  819 to reply to every one.
  820 You can click the "Done" button to reply
  821 indicating that you've implemented the reviewer's suggestion; otherwise,
  822 click on "Reply" and explain why you have not, or what you have done instead.
  823 </p>
  825 <p>
  826 It is perfectly normal for changes to go through several round of reviews,
  827 with one or more reviewers making new comments every time
  828 and then waiting for an updated change before reviewing again.
  829 This cycle happens even for experienced contributors, so
  830 don't be discouraged by it.
  831 </p>
  833 <h3 id="votes">Voting conventions</h3>
  835 <p>
  836 As they near a decision, reviewers will make a "vote" on your change.
  837 The Gerrit voting system involves an integer in the range -2 to +2:
  838 </p>
  840 <ul>
  841     <li>
  842     <b>+2</b> The change is approved for being merged.
  843     Only Go maintainers can cast a +2 vote.
  844     </li>
  845     <li>
  846     <b>+1</b> The change looks good, but either the reviewer is requesting
  847     minor changes before approving it, or they are not a maintainer and cannot
  848     approve it, but would like to encourage an approval.
  849     </li>
  850     <li>
  851     <b>-1</b> The change is not good the way it is but might be fixable.
  852     A -1 vote will always have a comment explaining why the change is unacceptable.
  853     </li>
  854     <li>
  855     <b>-2</b> The change is blocked by a maintainer and cannot be approved.
  856     Again, there will be a comment explaining the decision.
  857     </li>
  858 </ul>
  860 <h3 id="submit">Submitting an approved change</h3>
  862 <p>
  863 After the code has been +2'ed, an approver will
  864 apply it to the master branch using the Gerrit user interface.
  865 This is called "submitting the change".
  866 </p>
  868 <p>
  869 The two steps (approving and submitting) are separate because in some cases maintainers
  870 may want to approve it but not to submit it right away (for instance,
  871 the tree could be temporarily frozen).
  872 </p>
  874 <p>
  875 Submitting a change checks it into the repository.
  876 The change description will include a link to the code review,
  877 which will be updated with a link to the change
  878 in the repository.
  879 Since the method used to integrate the changes is Git's "Cherry Pick",
  880 the commit hashes in the repository will be changed by
  881 the submit operation.
  882 </p>
  884 <p>
  885 If your change has been approved for a few days without being
  886 submitted, feel free to write a comment in Gerrit requesting
  887 submission.
  888 </p>
  891 <h3 id="more_information">More information</h3>
  893 <p>
  894 In addition to the information here, the Go community maintains a <a
  895 href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page.
  896 Feel free to contribute to this page as you learn more about the review process.
  897 </p>
  901 <h2 id="advanced_topics">Miscellaneous topics</h2>
  903 <p>
  904 This section collects a number of other comments that are
  905 outside the issue/edit/code review/submit process itself.
  906 </p>
  909 <h3 id="copyright">Copyright headers</h3>
  911 <p>
  912 Files in the Go repository don't list author names, both to avoid clutter
  913 and to avoid having to keep the lists up to date.
  914 Instead, your name will appear in the
  915 <a href="https://golang.org/change">change log</a> and in the <a
  916 href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a
  917 href="/AUTHORS"><code>AUTHORS</code></a> file.
  918 These files are automatically generated from the commit logs periodically.
  919 The <a href="/AUTHORS"><code>AUTHORS</code></a> file defines who &ldquo;The Go
  920 Authors&rdquo;&mdash;the copyright holders&mdash;are.
  921 </p>
  923 <p>
  924 New files that you contribute should use the standard copyright header:
  925 </p>
  927 <pre>
  928 // Copyright 2020 The Go Authors. All rights reserved.
  929 // Use of this source code is governed by a BSD-style
  930 // license that can be found in the LICENSE file.
  931 </pre>
  933 <p>
  934 (Use the current year if you're reading this in 2021 or beyond.)
  935 Files in the repository are copyrighted the year they are added.
  936 Do not update the copyright year on files that you change.
  937 </p>
  942 <h3 id="troubleshooting_mail">Troubleshooting mail errors</h3>
  944 <p>
  945 The most common way that the <code>git</code> <code>codereview</code> <code>mail</code>
  946 command fails is because the e-mail address in the commit does not match the one
  947 that you used during <a href="#google_account">the registration process</a>.
  949 <br>
  950 If you see something like...
  951 </p>
  953 <pre>
  954 remote: Processing changes: refs: 1, done
  955 remote:
  956 remote: ERROR:  In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
  957 remote: ERROR:  author email address XXXXXXXXXXXXXXXXXXX
  958 remote: ERROR:  does not match your user account.
  959 </pre>
  961 <p>
  962 you need to configure Git for this repository to use the
  963 e-mail address that you registered with.
  964 To change the e-mail address to ensure this doesn't happen again, run:
  965 </p>
  967 <pre>
  968 $ git config user.email email@address.com
  969 </pre>
  971 <p>
  972 Then change the commit to use this alternative e-mail address with this command:
  973 </p>
  975 <pre>
  976 $ git commit --amend --author="Author Name &lt;email@address.com&gt;"
  977 </pre>
  979 <p>
  980 Then retry by running:
  981 </p>
  983 <pre>
  984 $ git codereview mail
  985 </pre>
  988 <h3 id="quick_test">Quickly testing your changes</h3>
  990 <p>
  991 Running <code>all.bash</code> for every single change to the code tree
  992 is burdensome.
  993 Even though it is strongly suggested to run it before
  994 sending a change, during the normal development cycle you may want
  995 to compile and test only the package you are developing.
  996 </p>
  998 <ul>
  999 <li>
 1000 In general, you can run <code>make.bash</code> instead of <code>all.bash</code>
 1001 to only rebuild the Go tool chain without running the whole test suite.
 1002 Or you
 1003 can run <code>run.bash</code> to only run the whole test suite without rebuilding
 1004 the tool chain.
 1005 You can think of <code>all.bash</code> as <code>make.bash</code>
 1006 followed by <code>run.bash</code>.
 1007 </li>
 1009 <li>
 1010 In this section, we'll call the directory into which you cloned the Go repository <code>$GODIR</code>.
 1011 The <code>go</code> tool built by <code>$GODIR/make.bash</code> will be installed
 1012 in <code>$GODIR/bin/go</code> and you
 1013 can invoke it to test your code.
 1014 For instance, if you
 1015 have modified the compiler and you want to test how it affects the
 1016 test suite of your own project, just run <code>go</code> <code>test</code>
 1017 using it:
 1019 <pre>
 1020 $ cd &lt;MYPROJECTDIR&gt;
 1021 $ $GODIR/bin/go test
 1022 </pre>
 1023 </li>
 1025 <li>
 1026 If you're changing the standard library, you probably don't need to rebuild
 1027 the compiler: you can just run the tests for the package you've changed.
 1028 You can do that either with the Go version you normally use, or
 1029 with the Go compiler built from your clone (which is
 1030 sometimes required because the standard library code you're modifying
 1031 might require a newer version than the stable one you have installed).
 1033 <pre>
 1034 $ cd $GODIR/src/hash/sha1
 1035 $ [make changes...]
 1036 $ $GODIR/bin/go test .
 1037 </pre>
 1038 </li>
 1040 <li>
 1041 If you're modifying the compiler itself, you can just recompile
 1042 the <code>compile</code> tool (which is the internal binary invoked
 1043 by <code>go</code> <code>build</code> to compile each single package).
 1044 After that, you will want to test it by compiling or running something.
 1046 <pre>
 1047 $ cd $GODIR/src
 1048 $ [make changes...]
 1049 $ $GODIR/bin/go install cmd/compile
 1050 $ $GODIR/bin/go build [something...]   # test the new compiler
 1051 $ $GODIR/bin/go run [something...]     # test the new compiler
 1052 $ $GODIR/bin/go test [something...]    # test the new compiler
 1053 </pre>
 1055 The same applies to other internal tools of the Go tool chain,
 1056 such as <code>asm</code>, <code>cover</code>, <code>link</code>, and so on.
 1057 Just recompile and install the tool using <code>go</code>
 1058 <code>install</code> <code>cmd/&lt;TOOL&gt;</code> and then use
 1059 the built Go binary to test it.
 1060 </li>
 1062 <li>
 1063 In addition to the standard per-package tests, there is a top-level
 1064 test suite in <code>$GODIR/test</code> that contains
 1065 several black-box and regression tests.
 1066 The test suite is run
 1067 by <code>all.bash</code> but you can also run it manually:
 1069 <pre>
 1070 $ cd $GODIR/test
 1071 $ $GODIR/bin/go run run.go
 1072 </pre>
 1073 </ul>
 1075 <h3 id="subrepos">Contributing to subrepositories (golang.org/x/...)</h3>
 1077 <p>
 1078 If you are contributing a change to a subrepository, obtain the
 1079 Go package using <code>go get</code>.
 1080 For example, to contribute
 1081 to <code>golang.org/x/oauth2</code>, check out the code by running:
 1082 </p>
 1084 <pre>
 1085 $ go get -d golang.org/x/oauth2/...
 1086 </pre>
 1088 <p>
 1089 Then, change your directory to the package's source directory
 1090 (<code>$GOPATH/src/golang.org/x/oauth2</code>), and follow the
 1091 normal contribution flow.
 1092 </p>
 1095 <h3 id="cc">Specifying a reviewer / CCing others</h3>
 1097 <p>
 1098 Unless explicitly told otherwise, such as in the discussion leading
 1099 up to sending in the change, it's better not to specify a reviewer.
 1100 All changes are automatically CC'ed to the
 1101 <a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a>
 1102 mailing list.
 1103 If this is your first ever change, there may be a moderation
 1104 delay before it appears on the mailing list, to prevent spam.
 1105 </p>
 1107 <p>
 1108 You can specify a reviewer or CC interested parties
 1109 using the <code>-r</code> or <code>-cc</code> options.
 1110 Both accept a comma-separated list of e-mail addresses:
 1111 </p>
 1113 <pre>
 1114 $ git codereview mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com
 1115 </pre>
 1118 <h3 id="sync">Synchronize your client</h3>
 1120 <p>
 1121 While you were working, others might have submitted changes to the repository.
 1122 To update your local branch, run
 1123 </p>
 1125 <pre>
 1126 $ git codereview sync
 1127 </pre>
 1129 <p>
 1130 (Under the covers this runs
 1131 <code>git</code> <code>pull</code> <code>-r</code>.)
 1132 </p>
 1135 <h3 id="download">Reviewing code by others</h3>
 1137 <p>
 1138 As part of the review process reviewers can propose changes directly (in the
 1139 GitHub workflow this would be someone else attaching commits to a pull request).
 1141 You can import these changes proposed by someone else into your local Git repository.
 1142 On the Gerrit review page, click the "Download ▼" link in the upper right
 1143 corner, copy the "Checkout" command and run it from your local Git repo.
 1144 It will look something like this:
 1145 </p>
 1147 <pre>
 1148 $ git fetch https://go.googlesource.com/review refs/changes/21/13245/1 &amp;&amp; git checkout FETCH_HEAD
 1149 </pre>
 1151 <p>
 1152 To revert, change back to the branch you were working in.
 1153 </p>
 1156 <h3 id="git-config">Set up git aliases</h3>
 1158 <p>
 1159 The <code>git-codereview</code> command can be run directly from the shell
 1160 by typing, for instance,
 1161 </p>
 1163 <pre>
 1164 $ git codereview sync
 1165 </pre>
 1167 <p>
 1168 but it is more convenient to set up aliases for <code>git-codereview</code>'s own
 1169 subcommands, so that the above becomes,
 1170 </p>
 1172 <pre>
 1173 $ git sync
 1174 </pre>
 1176 <p>
 1177 The <code>git-codereview</code> subcommands have been chosen to be distinct from
 1178 Git's own, so it's safe to define these aliases.
 1179 To install them, copy this text into your
 1180 Git configuration file (usually <code>.gitconfig</code> in your home directory):
 1181 </p>
 1183 <pre>
 1184 [alias]
 1185     change = codereview change
 1186     gofmt = codereview gofmt
 1187     mail = codereview mail
 1188     pending = codereview pending
 1189     submit = codereview submit
 1190     sync = codereview sync
 1191 </pre>
 1194 <h3 id="multiple_changes">Sending multiple dependent changes</h3>
 1196 <p>
 1197 Advanced users may want to stack up related commits in a single branch.
 1198 Gerrit allows for changes to be dependent on each other, forming such a dependency chain.
 1199 Each change will need to be approved and submitted separately but the dependency
 1200 will be visible to reviewers.
 1201 </p>
 1203 <p>
 1204 To send out a group of dependent changes, keep each change as a different commit under
 1205 the same branch, and then run:
 1206 </p>
 1208 <pre>
 1209 $ git codereview mail HEAD
 1210 </pre>
 1212 <p>
 1213 Make sure to explicitly specify <code>HEAD</code>, which is usually not required when sending
 1214 single changes.
 1215 </p>