github.com/miolini/go@v0.0.0-20160405192216-fca68c8cb408/doc/contribute.html (about) 1 <!--{ 2 "Title": "Contribution Guidelines" 3 }--> 4 5 <h2 id="Introduction">Introduction</h2> 6 7 <p> 8 This document explains how to contribute changes to the Go project. 9 It assumes you have followed the 10 <a href="/doc/install/source">installation instructions</a> and 11 have <a href="code.html">written and tested your code</a>. 12 </p> 13 14 <p> 15 (Note that the <code>gccgo</code> frontend lives elsewhere; 16 see <a href="gccgo_contribute.html">Contributing to gccgo</a>.) 17 </p> 18 19 <h2 id="Design">Discuss your design</h2> 20 21 <p> 22 The project welcomes submissions but please let everyone know what 23 you're working on if you want to change or add to the Go repositories. 24 </p> 25 26 <p> 27 Before undertaking to write something new for the Go project, 28 please <a href="https://golang.org/issue/new">file an issue</a> 29 (or claim an <a href="https://golang.org/issues">existing issue</a>). 30 Significant changes must go through the 31 <a href="https://golang.org/s/proposal-process">change proposal process</a> 32 before they can be accepted. 33 </p> 34 35 <p> 36 This process gives everyone a chance to validate the design, 37 helps prevent duplication of effort, 38 and ensures that the idea fits inside the goals for the language and tools. 39 It also checks that the design is sound before code is written; 40 the code review tool is not the place for high-level discussions. 41 </p> 42 43 <p> 44 When planning work, please note that the Go project follows a 45 <a href="https://golang.org/wiki/Go-Release-Cycle">six-month 46 development cycle</a>. The latter half of each cycle is a three-month 47 feature freeze during which only bug fixes and doc updates are accepted. 48 New work cannot be submitted during a feature freeze. 49 </p> 50 51 <h2 id="Testing">Testing redux</h2> 52 53 <p> 54 You've <a href="code.html">written and tested your code</a>, but 55 before sending code out for review, run all the tests for the whole 56 tree to make sure the changes don't break other packages or programs: 57 </p> 58 59 <pre> 60 $ cd go/src 61 $ ./all.bash 62 </pre> 63 64 <p> 65 (To build under Windows use <code>all.bat</code>.) 66 </p> 67 68 <p> 69 After running for a while, the command should print 70 "<code>ALL</code> <code>TESTS</code> <code>PASSED</code>". 71 </p> 72 73 <h2 id="Code_review">Code review</h2> 74 75 <p> 76 Changes to Go must be reviewed before they are accepted, 77 no matter who makes the change. 78 A custom git command called <code>git-codereview</code>, 79 discussed below, helps manage the code review process through a Google-hosted 80 <a href="https://go-review.googlesource.com/">instance</a> of the code review 81 system called <a href="https://www.gerritcodereview.com/">Gerrit</a>. 82 </p> 83 84 <h3 id="auth">Set up authentication for code review</h3> 85 86 <p> 87 Gerrit uses Google Accounts for authentication. If you don't have 88 a Google Account, you can create an account which 89 <a href="https://www.google.com/accounts/NewAccount">includes 90 a new Gmail email account</a> or create an account associated 91 <a href="https://accounts.google.com/SignUpWithoutGmail">with your existing 92 email address</a>. 93 </p> 94 95 <p> 96 The email address associated with the Google Account you use will be recorded in 97 the <a href="https://go.googlesource.com/go/+log/">change log</a> 98 and in the <a href="/CONTRIBUTORS">contributors file</a>. 99 </p> 100 101 <p> 102 To set up your account in Gerrit, visit 103 <a href="https://go.googlesource.com">go.googlesource.com</a> 104 and click on "Generate Password" in the page's top right menu bar. 105 </p> 106 107 <p> 108 You will be redirected to accounts.google.com to sign in. 109 </p> 110 111 <p> 112 Once signed in, you are returned back to go.googlesource.com to "Configure Git". 113 Follow the instructions on the page. 114 (If you are on a Windows computer, you should instead follow the instructions 115 in the yellow box to run the command.) 116 </p> 117 118 <p> 119 Your secret authentication token is now in a <code>.gitcookie</code> file 120 and Git is configured to use this file. 121 </p> 122 123 <h3 id="gerrit">Register with Gerrit</h3> 124 125 <p> 126 Now that you have your authentication token, 127 you need to register your account with Gerrit. 128 To do this, visit 129 <a href="https://go-review.googlesource.com/login/"> 130 go-review.googlesource.com/login/</a>. You will immediately be redirected 131 to Google Accounts. Sign in using the same Google Account you used above. 132 That is all that is required. 133 </p> 134 135 <h3 id="cla">Contributor License Agreement</h3> 136 137 <p>Gerrit serves as the gatekeeper and uses your e-mail address as the key. 138 To send your first change to the Go project from a given address, 139 you must have completed one of the contributor license agreements: 140 <ul> 141 <li> 142 If you are the copyright holder, you will need to agree to the 143 <a href="https://developers.google.com/open-source/cla/individual">individual 144 contributor license agreement</a>, which can be completed online. 145 </li> 146 <li> 147 If your organization is the copyright holder, the organization 148 will need to agree to the 149 <a href="https://developers.google.com/open-source/cla/corporate">corporate 150 contributor license agreement</a>. 151 (If the copyright holder for your code has already completed the 152 agreement in connection with another Google open source project, 153 it does not need to be completed again.) 154 </li> 155 </ul> 156 157 <p> 158 You can use the links above to create and sign the contributor license agreement 159 or you can show your current agreements and create new ones through the Gerrit 160 interface. <a href="https://go-review.googlesource.com/login/">Log into Gerrit</a>, 161 click your name in the upper-right, choose "Settings", then select "Agreements" 162 from the topics on the left. If you do not have a signed agreement listed here, 163 you can create one by clicking "New Contributor Agreement" and following the steps. 164 </p> 165 166 <p> 167 This rigmarole only needs to be done for your first submission for each email address. 168 </p> 169 170 <p> 171 If the copyright holder for the code you are submitting changes—for example, 172 if you start contributing code on behalf of a new company—please send email 173 to let us know, so that we can make sure an appropriate agreement is completed 174 and update the <code>AUTHORS</code> file. 175 </p> 176 177 <h3 id="git-codereview">Install the git-codereview command</h3> 178 179 <p> 180 Now install the <code>git-codereview</code> command by running, 181 </p> 182 183 <pre> 184 $ go get -u golang.org/x/review/git-codereview 185 </pre> 186 187 <p> 188 Make sure <code>git-codereview</code> is installed in your shell path, so that the 189 <code>git</code> command can find it. Check that 190 </p> 191 192 <pre> 193 $ git codereview help 194 </pre> 195 196 <p> 197 prints help text, not an error. 198 </p> 199 200 <p> 201 <b>Note to Git aficionados:</b> 202 The <code>git-codereview</code> command is not required to 203 upload and manage Gerrit code reviews. For those who prefer plain Git, the text 204 below gives the Git equivalent of each git-codereview command. 205 </p> 206 207 <p>If you do use plain 208 Git, note that you still need the commit hooks that the git-codereview command 209 configures; those hooks add a Gerrit <code>Change-Id</code> line to the commit 210 message and check that all Go source files have been formatted with gofmt. Even 211 if you intend to use plain Git for daily work, install the hooks in a new Git 212 checkout by running <code>git-codereview</code> <code>hooks</code>. 213 </p> 214 215 <p> 216 The workflow described below assumes a single change per branch. 217 It is also possible to prepare a sequence of (usually related) changes in a single branch. 218 See the <a href="https://golang.org/x/review/git-codereview">git-codereview documentation</a> for details. 219 </p> 220 221 <h3 id="git-config">Set up git aliases</h3> 222 223 <p> 224 The <code>git-codereview</code> command can be run directly from the shell 225 by typing, for instance, 226 </p> 227 228 <pre> 229 $ git codereview sync 230 </pre> 231 232 <p> 233 but it is more convenient to set up aliases for <code>git-codereview</code>'s own 234 subcommands, so that the above becomes, 235 </p> 236 237 <pre> 238 $ git sync 239 </pre> 240 241 <p> 242 The <code>git-codereview</code> subcommands have been chosen to be distinct from 243 Git's own, so it's safe to do so. 244 </p> 245 246 <p> 247 The aliases are optional, but in the rest of this document we will assume 248 they are installed. 249 To install them, copy this text into your Git configuration file 250 (usually <code>.gitconfig</code> in your home directory): 251 </p> 252 253 <pre> 254 [alias] 255 change = codereview change 256 gofmt = codereview gofmt 257 mail = codereview mail 258 pending = codereview pending 259 submit = codereview submit 260 sync = codereview sync 261 </pre> 262 263 <h3 id="help">Understanding the git-codereview command</h3> 264 265 <p>After installing the <code>git-codereview</code> command, you can run</p> 266 267 <pre> 268 $ git codereview help 269 </pre> 270 271 <p> 272 to learn more about its commands. 273 You can also read the <a href="https://godoc.org/golang.org/x/review/git-codereview">command documentation</a>. 274 </p> 275 276 <h3 id="master">Switch to the master branch</h3> 277 278 <p> 279 Most Go installations use a release branch, but new changes should 280 only be made based on the master branch. 281 (They may be applied later to a release branch as part of the release process, 282 but most contributors won't do this themselves.) 283 Before making a change, make sure you start on the master branch: 284 </p> 285 286 <pre> 287 $ git checkout master 288 $ git sync 289 </pre> 290 291 <p> 292 (In Git terms, <code>git</code> <code>sync</code> runs 293 <code>git</code> <code>pull</code> <code>-r</code>.) 294 </p> 295 296 <h3 id="change">Make a change</h3> 297 298 <p> 299 The entire checked-out tree is writable. 300 Once you have edited files, you must tell Git that they have been modified. 301 You must also tell Git about any files that are added, removed, or renamed files. 302 These operations are done with the usual Git commands, 303 <code>git</code> <code>add</code>, 304 <code>git</code> <code>rm</code>, 305 and 306 <code>git</code> <code>mv</code>. 307 </p> 308 309 <p> 310 If you wish to checkpoint your work, or are ready to send the code out for review, run</p> 311 312 <pre> 313 $ git change <i><branch></i> 314 </pre> 315 316 <p> 317 from any directory in your Go repository to commit the changes so far. 318 The name <i><branch></i> is an arbitrary one you choose to identify the 319 local branch containing your changes. 320 </p> 321 322 <p> 323 (In Git terms, <code>git</code> <code>change</code> <code><branch></code> 324 runs <code>git</code> <code>checkout</code> <code>-b</code> <code>branch</code>, 325 then <code>git</code> <code>branch</code> <code>--set-upstream-to</code> <code>origin/master</code>, 326 then <code>git</code> <code>commit</code>.) 327 </p> 328 329 <p> 330 Git will open a change description file in your editor. 331 (It uses the editor named by the <code>$EDITOR</code> environment variable, 332 <code>vi</code> by default.) 333 The file will look like: 334 </p> 335 336 <pre> 337 338 # Please enter the commit message for your changes. Lines starting 339 # with '#' will be ignored, and an empty message aborts the commit. 340 # On branch foo 341 # Changes not staged for commit: 342 # modified: editedfile.go 343 # 344 </pre> 345 346 <p> 347 At the beginning of this file is a blank line; replace it 348 with a thorough description of your change. 349 The first line of the change description is conventionally a one-line 350 summary of the change, prefixed by the primary affected package, 351 and is used as the subject for code review mail. 352 The rest of the 353 description elaborates and should provide context for the 354 change and explain what it does. 355 If there is a helpful reference, mention it here. 356 </p> 357 358 <p> 359 After editing, the template might now read: 360 </p> 361 362 <pre> 363 math: improved Sin, Cos and Tan precision for very large arguments 364 365 The existing implementation has poor numerical properties for 366 large arguments, so use the McGillicutty algorithm to improve 367 accuracy above 1e10. 368 369 The algorithm is described at http://wikipedia.org/wiki/McGillicutty_Algorithm 370 371 Fixes #159 372 373 # Please enter the commit message for your changes. Lines starting 374 # with '#' will be ignored, and an empty message aborts the commit. 375 # On branch foo 376 # Changes not staged for commit: 377 # modified: editedfile.go 378 # 379 </pre> 380 381 <p> 382 The commented section of the file lists all the modified files in your client. 383 It is best to keep unrelated changes in different change lists, 384 so if you see a file listed that should not be included, abort 385 the command and move that file to a different branch. 386 </p> 387 388 <p> 389 The special notation "Fixes #159" associates the change with issue 159 in the 390 <a href="https://golang.org/issue/159">Go issue tracker</a>. 391 When this change is eventually submitted, the issue 392 tracker will automatically mark the issue as fixed. 393 (There are several such conventions, described in detail in the 394 <a href="https://help.github.com/articles/closing-issues-via-commit-messages/">GitHub Issue Tracker documentation</a>.) 395 </p> 396 397 <p> 398 Once you have finished writing the commit message, 399 save the file and exit the editor. 400 </p> 401 402 <p> 403 If you wish to do more editing, re-stage your changes using 404 <code>git</code> <code>add</code>, and then run 405 </p> 406 407 <pre> 408 $ git change 409 </pre> 410 411 <p> 412 to update the change description and incorporate the staged changes. The 413 change description contains a <code>Change-Id</code> line near the bottom, 414 added by a Git commit hook during the initial 415 <code>git</code> <code>change</code>. 416 That line is used by Gerrit to match successive uploads of the same change. 417 Do not edit or delete it. 418 </p> 419 420 <p> 421 (In Git terms, <code>git</code> <code>change</code> with no branch name 422 runs <code>git</code> <code>commit</code> <code>--amend</code>.) 423 </p> 424 425 <h3 id="mail">Mail the change for review</h3> 426 427 <p> 428 Once the change is ready, mail it out for review: 429 </p> 430 431 <pre> 432 $ git mail 433 </pre> 434 435 <p> 436 You can specify a reviewer or CC interested parties 437 using the <code>-r</code> or <code>-cc</code> options. 438 Both accept a comma-separated list of email addresses: 439 </p> 440 441 <pre> 442 $ git mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com 443 </pre> 444 445 <p> 446 Unless explicitly told otherwise, such as in the discussion leading 447 up to sending in the change list, it's better not to specify a reviewer. 448 All changes are automatically CC'ed to the 449 <a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a> 450 mailing list. If this is your first ever change, there may be a moderation 451 delay before it appears on the mailing list, to prevent spam. 452 </p> 453 454 <p> 455 (In Git terms, <code>git</code> <code>mail</code> pushes the local committed 456 changes to Gerrit using <code>git</code> <code>push</code> <code>origin</code> 457 <code>HEAD:refs/for/master</code>.) 458 </p> 459 460 <p> 461 If your change relates to an open issue, please add a comment to the issue 462 announcing your proposed fix, including a link to your CL. 463 </p> 464 465 <p> 466 The code review server assigns your change an issue number and URL, 467 which <code>git</code> <code>mail</code> will print, something like: 468 </p> 469 470 <pre> 471 remote: New Changes: 472 remote: https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments 473 </pre> 474 475 <h3 id="review">Reviewing code</h3> 476 477 <p> 478 Running <code>git</code> <code>mail</code> will send an email to you and the 479 reviewers asking them to visit the issue's URL and make comments on the change. 480 When done, the reviewer adds comments through the Gerrit user interface 481 and clicks "Reply" to send comments back. 482 You will receive a mail notification when this happens. 483 You must reply through the web interface. 484 (Unlike with the old Rietveld review system, replying by mail has no effect.) 485 </p> 486 487 <h3 id="revise">Revise and upload</h3> 488 489 <p> 490 You must respond to review comments through the web interface. 491 (Unlike with the old Rietveld review system, responding by mail has no effect.) 492 </p> 493 494 <p> 495 When you have revised the code and are ready for another round of review, 496 stage those changes and use <code>git</code> <code>change</code> to update the 497 commit. 498 To send the update change list for another round of review, 499 run <code>git</code> <code>mail</code> again. 500 </p> 501 502 <p> 503 The reviewer can comment on the new copy, and the process repeats. 504 The reviewer approves the change by giving it a positive score 505 (+1 or +2) and replying <code>LGTM</code>: looks good to me. 506 </p> 507 508 <p> 509 You can see a list of your pending changes by running <code>git</code> 510 <code>pending</code>, and switch between change branches with <code>git</code> 511 <code>change</code> <code><i><branch></i></code>. 512 </p> 513 514 <h3 id="sync">Synchronize your client</h3> 515 516 <p> 517 While you were working, others might have submitted changes to the repository. 518 To update your local branch, run 519 </p> 520 521 <pre> 522 $ git sync 523 </pre> 524 525 <p> 526 (In git terms, <code>git</code> <code>sync</code> runs 527 <code>git</code> <code>pull</code> <code>-r</code>.) 528 </p> 529 530 <p> 531 If files you were editing have changed, Git does its best to merge the 532 remote changes into your local changes. 533 It may leave some files to merge by hand. 534 </p> 535 536 <p> 537 For example, suppose you have edited <code>sin.go</code> but 538 someone else has committed an independent change. 539 When you run <code>git</code> <code>sync</code>, 540 you will get the (scary-looking) output: 541 542 <pre> 543 $ git sync 544 Failed to merge in the changes. 545 Patch failed at 0023 math: improved Sin, Cos and Tan precision for very large arguments 546 The copy of the patch that failed is found in: 547 /home/you/repo/.git/rebase-apply/patch 548 549 When you have resolved this problem, run "git rebase --continue". 550 If you prefer to skip this patch, run "git rebase --skip" instead. 551 To check out the original branch and stop rebasing, run "git rebase --abort". 552 </pre> 553 554 <p> 555 If this happens, run 556 </p> 557 558 <pre> 559 $ git status 560 </pre> 561 562 <p> 563 to see which files failed to merge. 564 The output will look something like this: 565 </p> 566 567 <pre> 568 rebase in progress; onto a24c3eb 569 You are currently rebasing branch 'mcgillicutty' on 'a24c3eb'. 570 (fix conflicts and then run "git rebase --continue") 571 (use "git rebase --skip" to skip this patch) 572 (use "git rebase --abort" to check out the original branch) 573 574 Unmerged paths: 575 (use "git reset HEAD <file>..." to unstage) 576 (use "git add <file>..." to mark resolution) 577 578 <i>both modified: sin.go</i> 579 </pre> 580 581 <p> 582 The only important part in that transcript is the italicized "both modified" 583 line: Git failed to merge your changes with the conflicting change. 584 When this happens, Git leaves both sets of edits in the file, 585 with conflicts marked by <code><<<<<<<</code> and 586 <code>>>>>>>></code>. 587 It is now your job to edit the file to combine them. 588 Continuing the example, searching for those strings in <code>sin.go</code> 589 might turn up: 590 </p> 591 592 <pre> 593 arg = scale(arg) 594 <<<<<<< HEAD 595 if arg < 1e9 { 596 ======= 597 if arg < 1e10 { 598 >>>>>>> mcgillicutty 599 largeReduce(arg) 600 </pre> 601 602 <p> 603 Git doesn't show it, but suppose the original text that both edits 604 started with was 1e8; you changed it to 1e10 and the other change to 1e9, 605 so the correct answer might now be 1e10. First, edit the section 606 to remove the markers and leave the correct code: 607 </p> 608 609 <pre> 610 arg = scale(arg) 611 if arg < 1e10 { 612 largeReduce(arg) 613 </pre> 614 615 <p> 616 Then tell Git that the conflict is resolved by running 617 </p> 618 619 <pre> 620 $ git add sin.go 621 </pre> 622 623 <p> 624 If you had been editing the file, say for debugging, but do not 625 care to preserve your changes, you can run 626 <code>git</code> <code>reset</code> <code>HEAD</code> <code>sin.go</code> 627 to abandon your changes. 628 Then run <code>git</code> <code>rebase</code> <code>--continue</code> to 629 restore the change commit. 630 </p> 631 632 <h3 id="download">Reviewing code by others</h3> 633 634 <p> 635 You can import a change proposed by someone else into your local Git repository. 636 On the Gerrit review page, click the "Download ▼" link in the upper right 637 corner, copy the "Checkout" command and run it from your local Git repo. 638 It should look something like this: 639 </p> 640 641 <pre> 642 $ git fetch https://go.googlesource.com/review refs/changes/21/1221/1 && git checkout FETCH_HEAD 643 </pre> 644 645 <p> 646 To revert, change back to the branch you were working in. 647 </p> 648 649 <h3 id="submit">Submit the change after the review</h3> 650 651 <p> 652 After the code has been <code>LGTM</code>'ed, an approver may 653 submit it to the master branch using the Gerrit UI. 654 There is a "Submit" button on the web page for the change 655 that appears once the change is approved (marked +2). 656 </p> 657 658 <p> 659 This checks the change into the repository. 660 The change description will include a link to the code review, 661 and the code review will be updated with a link to the change 662 in the repository. 663 Since the method used to integrate the changes is "Cherry Pick", 664 the commit hashes in the repository will be changed by 665 the submit operation. 666 </p> 667 668 <h3 id="more">More information</h3> 669 670 <p> 671 In addition to the information here, the Go community maintains a <a href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page. 672 Feel free to contribute to this page as you learn the review process. 673 </p> 674 675 <h2 id="copyright">Copyright</h2> 676 677 <p>Files in the Go repository don't list author names, 678 both to avoid clutter and to avoid having to keep the lists up to date. 679 Instead, your name will appear in the 680 <a href="https://golang.org/change">change log</a> 681 and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file 682 and perhaps the <a href="/AUTHORS"><code>AUTHORS</code></a> file. 683 </p> 684 685 <p>The <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file 686 defines who the Go contributors—the people—are; 687 the <a href="/AUTHORS"><code>AUTHORS</code></a> file defines 688 who “The Go Authors”—the copyright holders—are. 689 These files will be periodically updated based on the commit logs. 690 691 <p>Code that you contribute should use the standard copyright header:</p> 692 693 <pre> 694 // Copyright 2016 The Go Authors. All rights reserved. 695 // Use of this source code is governed by a BSD-style 696 // license that can be found in the LICENSE file. 697 </pre> 698 699 <p> 700 Files in the repository are copyright the year they are added. It is not 701 necessary to update the copyright year on files that you change. 702 </p>