"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 }-->
    4 
    5 <p>
    6 The Go project welcomes all contributors.
    7 </p>
    8 
    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>
   15 
   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>
   21 
   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>
   26 
   27 <h2 id="contributor">Becoming a contributor</h2>
   28 
   29 <h3 id="contrib_overview">Overview</h3>
   30 
   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>
   35 
   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>
   62 
   63 <p>
   64 If you prefer, there is an automated tool that walks through these steps.
   65 Just run:
   66 </p>
   67 
   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>
   73 
   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>
   79 
   80 <h3 id="google_account">Step 0: Select a Google Account</h3>
   81 
   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>
   94 
   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>
  104 
  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>
  112 
  113 <pre>
  114 $ git config --global user.email  # check current global config
  115 $ git config user.email           # check current local config
  116 </pre>
  117 
  118 <p>
  119 To change the configured address:
  120 </p>
  121 
  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>
  126 
  127 
  128 <h3 id="cla">Step 1: Contributor License Agreement</h3>
  129 
  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>
  135 
  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>
  149 
  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>
  158 
  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>
  167 
  168 
  169 <h3 id="config_git_auth">Step 2: Configure git authentication</h3>
  170 
  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>
  179 
  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>
  201 
  202 <h3 id="auth">Step 3: Create a Gerrit account </h3>
  203 
  204 <p>
  205 Gerrit is an open-source tool used by Go maintainers to discuss and review
  206 code submissions.
  207 </p>
  208 
  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>
  213 
  214 <h3 id="git-codereview_install">Step 4: Install the git-codereview command</h3>
  215 
  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>
  221 
  222 <p>
  223 Install the <code>git-codereview</code> command by running,
  224 </p>
  225 
  226 <pre>
  227 $ go get -u golang.org/x/review/git-codereview
  228 </pre>
  229 
  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>
  235 
  236 <pre>
  237 $ git codereview help
  238 </pre>
  239 
  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>
  244 
  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>
  252 
  253 
  254 <h2 id="before_contributing">Before contributing code</h2>
  255 
  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>
  265 
  266 <h3 id="check_tracker">Check the issue tracker</h3>
  267 
  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>
  274 
  275 <p>
  276 Most issues will be marked with one of the following workflow labels:
  277 </p>
  278 
  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>
  297 
  298 <p>
  299 You can use GitHub's search functionality to find issues to help out with. Examples:
  300 </p>
  301 
  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>
  316 
  317 <h3 id="design">Open an issue for any new problem</h3>
  318 
  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>
  329 
  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>
  338 
  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>
  345 
  346 <p>
  347 Sensitive security-related issues (only!) should be reported to <a href="mailto:security@golang.org">security@golang.org</a>.
  348 </p>
  349 
  350 <h2 id="sending_a_change_github">Sending a change via GitHub</h2>
  351 
  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>
  360 
  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>
  369 
  370 <p>
  371 Some things to keep in mind:
  372 </p>
  373 
  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>
  393 
  394 <h2 id="sending_a_change_gerrit">Sending a change via Gerrit</h2>
  395 
  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>
  402 
  403 <h3 id="gerrit_overview">Overview</h3>
  404 
  405 <p>
  406 This is an overview of the overall process:
  407 </p>
  408 
  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>
  419 
  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>
  435 
  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>
  442 
  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>
  450 
  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>
  462 
  463 <p>
  464 The rest of this section describes these steps in more detail.
  465 </p>
  466 
  467 
  468 <h3 id="checkout_go">Step 1: Clone the Go source code</h3>
  469 
  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>
  477 
  478 <pre>
  479 $ git clone https://go.googlesource.com/go
  480 $ cd go
  481 </pre>
  482 
  483 <h3 id="make_branch">Step 2: Prepare changes in a new branch</h3>
  484 
  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>
  491 
  492 <pre>
  493 $ git checkout -b mybranch
  494 $ [edit files...]
  495 $ git add [files...]
  496 </pre>
  497 
  498 <p>
  499 To commit changes, instead of <code>git commit</code>, use <code>git codereview change</code>.
  500 </p>
  501 
  502 <pre>
  503 $ git codereview change
  504 (open $EDITOR)
  505 </pre>
  506 
  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>
  515 
  516 <pre>
  517 Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990
  518 </pre>
  519 
  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>
  525 
  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>
  531 
  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>
  539 
  540 
  541 <h3 id="testing">Step 3: Test your changes</h3>
  542 
  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>
  548 
  549 <pre>
  550 $ cd go/src
  551 $ ./all.bash
  552 </pre>
  553 
  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>
  559 
  560 <p>
  561 After running for a while and printing a lot of testing output, the command should finish
  562 by printing,
  563 </p>
  564 
  565 <pre>
  566 ALL TESTS PASSED
  567 </pre>
  568 
  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>
  578 
  579 <h3 id="mail">Step 4: Send changes for review</h3>
  580 
  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>
  586 
  587 <pre>
  588 $ git codereview mail
  589 </pre>
  590 
  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>
  594 
  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>
  599 
  600 <p>
  601 If you get an error instead, check the
  602 <a href="#troubleshooting_mail">Troubleshooting mail errors</a> section.
  603 </p>
  604 
  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>
  610 
  611 
  612 <h3 id="revise">Step 5: Revise changes after a review</h3>
  613 
  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>
  621 
  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>
  628 
  629 <pre>
  630 $ git codereview change     # amend current commit
  631 (open $EDITOR)
  632 $ git codereview mail       # send new changes to Gerrit
  633 </pre>
  634 
  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>
  639 
  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>
  647 
  648 <h2 id="commit_messages">Good commit messages</h2>
  649 
  650 <p>
  651 Commit messages in Go follow a specific set of conventions,
  652 which we discuss in this section.
  653 </p>
  654 
  655 <p>
  656 Here is an example of a good one:
  657 </p>
  658 
  659 <pre>
  660 math: improve Sin, Cos and Tan precision for very large arguments
  661 
  662 The existing implementation has poor numerical properties for
  663 large arguments, so use the McGillicutty algorithm to improve
  664 accuracy above 1e10.
  665 
  666 The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm
  667 
  668 Fixes #159
  669 </pre>
  670 
  671 <h3 id="first_line">First line</h3>
  672 
  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>
  677 
  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>
  684 
  685 <p>
  686 Follow the first line by a blank line.
  687 </p>
  688 
  689 <h3 id="main_content">Main content</h3>
  690 
  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>
  698 
  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>
  706 
  707 <h3 id="ref_issues">Referencing issues</h3>
  708 
  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>
  715 
  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>
  723 
  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>
  731 
  732 
  733 <h2 id="review">The review process</h2>
  734 
  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>
  739 
  740 
  741 <h3 id="mistakes">Common beginner mistakes</h3>
  742 
  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>
  749 
  750 <ul>
  751 <li>
  752 Commit message not following the <a href="#commit_messages">suggested
  753 format</a>.
  754 </li>
  755 
  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>
  767 
  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>
  779 
  780 <h3 id="trybots">Trybots</h3>
  781 
  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>
  789 
  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>
  797 
  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>
  807 
  808 <h3 id="reviews">Reviews</h3>
  809 
  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>
  816 
  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>
  824 
  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>
  832 
  833 <h3 id="votes">Voting conventions</h3>
  834 
  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>
  839 
  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>
  859 
  860 <h3 id="submit">Submitting an approved change</h3>
  861 
  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>
  867 
  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>
  873 
  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>
  883 
  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>
  889 
  890 
  891 <h3 id="more_information">More information</h3>
  892 
  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>
  898 
  899 
  900 
  901 <h2 id="advanced_topics">Miscellaneous topics</h2>
  902 
  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>
  907 
  908 
  909 <h3 id="copyright">Copyright headers</h3>
  910 
  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>
  922 
  923 <p>
  924 New files that you contribute should use the standard copyright header:
  925 </p>
  926 
  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>
  932 
  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>
  938 
  939 
  940 
  941 
  942 <h3 id="troubleshooting_mail">Troubleshooting mail errors</h3>
  943 
  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>.
  948 
  949 <br>
  950 If you see something like...
  951 </p>
  952 
  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>
  960 
  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>
  966 
  967 <pre>
  968 $ git config user.email email@address.com
  969 </pre>
  970 
  971 <p>
  972 Then change the commit to use this alternative e-mail address with this command:
  973 </p>
  974 
  975 <pre>
  976 $ git commit --amend --author="Author Name &lt;email@address.com&gt;"
  977 </pre>
  978 
  979 <p>
  980 Then retry by running:
  981 </p>
  982 
  983 <pre>
  984 $ git codereview mail
  985 </pre>
  986 
  987 
  988 <h3 id="quick_test">Quickly testing your changes</h3>
  989 
  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>
  997 
  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>
 1008 
 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:
 1018 
 1019 <pre>
 1020 $ cd &lt;MYPROJECTDIR&gt;
 1021 $ $GODIR/bin/go test
 1022 </pre>
 1023 </li>
 1024 
 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).
 1032 
 1033 <pre>
 1034 $ cd $GODIR/src/hash/sha1
 1035 $ [make changes...]
 1036 $ $GODIR/bin/go test .
 1037 </pre>
 1038 </li>
 1039 
 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.
 1045 
 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>
 1054 
 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>
 1061 
 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:
 1068 
 1069 <pre>
 1070 $ cd $GODIR/test
 1071 $ $GODIR/bin/go run run.go
 1072 </pre>
 1073 </ul>
 1074 
 1075 <h3 id="subrepos">Contributing to subrepositories (golang.org/x/...)</h3>
 1076 
 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>
 1083 
 1084 <pre>
 1085 $ go get -d golang.org/x/oauth2/...
 1086 </pre>
 1087 
 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>
 1093 
 1094 
 1095 <h3 id="cc">Specifying a reviewer / CCing others</h3>
 1096 
 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>
 1106 
 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>
 1112 
 1113 <pre>
 1114 $ git codereview mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com
 1115 </pre>
 1116 
 1117 
 1118 <h3 id="sync">Synchronize your client</h3>
 1119 
 1120 <p>
 1121 While you were working, others might have submitted changes to the repository.
 1122 To update your local branch, run
 1123 </p>
 1124 
 1125 <pre>
 1126 $ git codereview sync
 1127 </pre>
 1128 
 1129 <p>
 1130 (Under the covers this runs
 1131 <code>git</code> <code>pull</code> <code>-r</code>.)
 1132 </p>
 1133 
 1134 
 1135 <h3 id="download">Reviewing code by others</h3>
 1136 
 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).
 1140 
 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>
 1146 
 1147 <pre>
 1148 $ git fetch https://go.googlesource.com/review refs/changes/21/13245/1 &amp;&amp; git checkout FETCH_HEAD
 1149 </pre>
 1150 
 1151 <p>
 1152 To revert, change back to the branch you were working in.
 1153 </p>
 1154 
 1155 
 1156 <h3 id="git-config">Set up git aliases</h3>
 1157 
 1158 <p>
 1159 The <code>git-codereview</code> command can be run directly from the shell
 1160 by typing, for instance,
 1161 </p>
 1162 
 1163 <pre>
 1164 $ git codereview sync
 1165 </pre>
 1166 
 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>
 1171 
 1172 <pre>
 1173 $ git sync
 1174 </pre>
 1175 
 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>
 1182 
 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>
 1192 
 1193 
 1194 <h3 id="multiple_changes">Sending multiple dependent changes</h3>
 1195 
 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>
 1202 
 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>
 1207 
 1208 <pre>
 1209 $ git codereview mail HEAD
 1210 </pre>
 1211 
 1212 <p>
 1213 Make sure to explicitly specify <code>HEAD</code>, which is usually not required when sending
 1214 single changes.
 1215 </p>