diff options
Diffstat (limited to 'doc/contribute.html')
| -rw-r--r-- | doc/contribute.html | 1294 |
1 files changed, 0 insertions, 1294 deletions
diff --git a/doc/contribute.html b/doc/contribute.html deleted file mode 100644 index 66a47eb07e..0000000000 --- a/doc/contribute.html +++ /dev/null @@ -1,1294 +0,0 @@ -<!--{ - "Title": "Contribution Guide" -}--> - -<p> -The Go project welcomes all contributors. -</p> - -<p> -This document is a guide to help you through the process -of contributing to the Go project, which is a little different -from that used by other open source projects. -We assume you have a basic understanding of Git and Go. -</p> - -<p> -In addition to the information here, the Go community maintains a -<a href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page. -Feel free to contribute to the wiki as you learn the review process. -</p> - -<p> -Note that the <code>gccgo</code> front end lives elsewhere; -see <a href="gccgo_contribute.html">Contributing to gccgo</a>. -</p> - -<h2 id="contributor">Becoming a contributor</h2> - -<h3 id="contrib_overview">Overview</h3> - -<p> -The first step is registering as a Go contributor and configuring your environment. -Here is a checklist of the required steps to follow: -</p> - -<ul> -<li> -<b>Step 0</b>: Decide on a single Google Account you will be using to contribute to Go. -Use that account for all the following steps and make sure that <code>git</code> -is configured to create commits with that account's e-mail address. -</li> -<li> -<b>Step 1</b>: <a href="https://cla.developers.google.com/clas">Sign and submit</a> a -CLA (Contributor License Agreement). -</li> -<li> -<b>Step 2</b>: Configure authentication credentials for the Go Git repository. -Visit <a href="https://go.googlesource.com">go.googlesource.com</a>, click -"Generate Password" in the page's top right menu bar, and follow the -instructions. -</li> -<li> -<b>Step 3</b>: Register for Gerrit, the code review tool used by the Go team, -by <a href="https://go-review.googlesource.com/login/">visiting this page</a>. -The CLA and the registration need to be done only once for your account. -</li> -<li> -<b>Step 4</b>: Install <code>git-codereview</code> by running -<code>go get -u golang.org/x/review/git-codereview</code> -</li> -</ul> - -<p> -If you prefer, there is an automated tool that walks through these steps. -Just run: -</p> - -<pre> -$ go get -u golang.org/x/tools/cmd/go-contrib-init -$ cd /code/to/edit -$ go-contrib-init -</pre> - -<p> -The rest of this chapter elaborates on these instructions. -If you have completed the steps above (either manually or through the tool), jump to -<a href="#before_contributing">Before contributing code</a>. -</p> - -<h3 id="google_account">Step 0: Select a Google Account</h3> - -<p> -A contribution to Go is made through a Google account with a specific -e-mail address. -Make sure to use the same account throughout the process and -for all your subsequent contributions. -You may need to decide whether to use a personal address or a corporate address. -The choice will depend on who -will own the copyright for the code that you will be writing -and submitting. -You might want to discuss this topic with your employer before deciding which -account to use. -</p> - -<p> -Google accounts can either be Gmail e-mail accounts, G Suite organization accounts, or -accounts associated with an external e-mail address. -For instance, if you need to use -an existing corporate e-mail that is not managed through G Suite, you can create -an account associated -<a href="https://accounts.google.com/SignUpWithoutGmail">with your existing -e-mail address</a>. -</p> - -<p> -You also need to make sure that your Git tool is configured to create commits -using your chosen e-mail address. -You can either configure Git globally -(as a default for all projects), or locally (for a single specific project). -You can check the current configuration with this command: -</p> - -<pre> -$ git config --global user.email # check current global config -$ git config user.email # check current local config -</pre> - -<p> -To change the configured address: -</p> - -<pre> -$ git config --global user.email name@example.com # change global config -$ git config user.email name@example.com # change local config -</pre> - - -<h3 id="cla">Step 1: Contributor License Agreement</h3> - -<p> -Before sending your first change to the Go project -you must have completed one of the following two CLAs. -Which CLA you should sign depends on who owns the copyright to your work. -</p> - -<ul> -<li> -If you are the copyright holder, you will need to agree to the -<a href="https://developers.google.com/open-source/cla/individual">individual -contributor license agreement</a>, which can be completed online. -</li> -<li> -If your organization is the copyright holder, the organization -will need to agree to the -<a href="https://developers.google.com/open-source/cla/corporate">corporate -contributor license agreement</a>.<br> -</li> -</ul> - -<p> -You can check your currently signed agreements and sign new ones at -the <a href="https://cla.developers.google.com/clas?pli=1&authuser=1">Google Developers -Contributor License Agreements</a> website. -If the copyright holder for your contribution has already completed the -agreement in connection with another Google open source project, -it does not need to be completed again. -</p> - -<p> -If the copyright holder for the code you are submitting changes—for example, -if you start contributing code on behalf of a new company—please send mail -to the <a href="mailto:golang-dev@googlegroups.com"><code>golang-dev</code> -mailing list</a>. -This will let us know the situation so we can make sure an appropriate agreement is -completed and update the <code>AUTHORS</code> file. -</p> - - -<h3 id="config_git_auth">Step 2: Configure git authentication</h3> - -<p> -The main Go repository is located at -<a href="https://go.googlesource.com">go.googlesource.com</a>, -a Git server hosted by Google. -Authentication on the web server is made through your Google account, but -you also need to configure <code>git</code> on your computer to access it. -Follow these steps: -</p> - -<ol> -<li> -Visit <a href="https://go.googlesource.com">go.googlesource.com</a> -and click on "Generate Password" in the page's top right menu bar. -You will be redirected to accounts.google.com to sign in. -</li> -<li> -After signing in, you will be taken to a page with the title "Configure Git". -This page contains a personalized script that when run locally will configure Git -to hold your unique authentication key. -This key is paired with one that is generated and stored on the server, -analogous to how SSH keys work. -</li> -<li> -Copy and run this script locally in your terminal to store your secret -authentication token in a <code>.gitcookies</code> file. -If you are using a Windows computer and running <code>cmd</code>, -you should instead follow the instructions in the yellow box to run the command; -otherwise run the regular script. -</li> -</ol> - -<h3 id="auth">Step 3: Create a Gerrit account </h3> - -<p> -Gerrit is an open-source tool used by Go maintainers to discuss and review -code submissions. -</p> - -<p> -To register your account, visit <a href="https://go-review.googlesource.com/login/"> -go-review.googlesource.com/login/</a> and sign in once using the same Google Account you used above. -</p> - -<h3 id="git-codereview_install">Step 4: Install the git-codereview command</h3> - -<p> -Changes to Go must be reviewed before they are accepted, no matter who makes the change. -A custom <code>git</code> command called <code>git-codereview</code> -simplifies sending changes to Gerrit. -</p> - -<p> -Install the <code>git-codereview</code> command by running, -</p> - -<pre> -$ go get -u golang.org/x/review/git-codereview -</pre> - -<p> -Make sure <code>git-codereview</code> is installed in your shell path, so that the -<code>git</code> command can find it. -Check that -</p> - -<pre> -$ git codereview help -</pre> - -<p> -prints help text, not an error. If it prints an error, make sure that -<code>$GOPATH/bin</code> is in your <code>$PATH</code>. -</p> - -<p> -On Windows, when using git-bash you must make sure that -<code>git-codereview.exe</code> is in your <code>git</code> exec-path. -Run <code>git --exec-path</code> to discover the right location then create a -symbolic link or just copy the executable from <code>$GOPATH/bin</code> to this -directory. -</p> - - -<h2 id="before_contributing">Before contributing code</h2> - -<p> -The project welcomes code patches, but to make sure things are well -coordinated you should discuss any significant change before starting -the work. -It's recommended that you signal your intention to contribute in the -issue tracker, either by <a href="https://golang.org/issue/new">filing -a new issue</a> or by claiming -an <a href="https://golang.org/issues">existing one</a>. -</p> - -<h3 id="where">Where to contribute</h3> - -<p> -The Go project consists of the main -<a href="https://go.googlesource.com/go">go</a> repository, which contains the -source code for the Go language, as well as many golang.org/x/... repostories. -These contain the various tools and infrastructure that support Go. For -example, <a href="https://go.googlesource.com/pkgsite">golang.org/x/pkgsite</a> -is for <a href="https://pkg.go.dev">pkg.go.dev</a>, -<a href="https://go.googlesource.com/playground">golang.org/x/playground</a> -is for the Go playground, and -<a href="https://go.googlesource.com/tools">golang.org/x/tools</a> contains -a variety of Go tools, including the Go language server, -<a href="https://golang.org/s/gopls">gopls</a>. You can see a -list of all the golang.org/x/... repositories on -<a href="https://go.googlesource.com">go.googlesource.com</a>. -</p> - -<h3 id="check_tracker">Check the issue tracker</h3> - -<p> -Whether you already know what contribution to make, or you are searching for -an idea, the <a href="https://github.com/golang/go/issues">issue tracker</a> is -always the first place to go. -Issues are triaged to categorize them and manage the workflow. -</p> - -<p> -The majority of the golang.org/x/... repos also use the main Go -issue tracker. However, a few of these repositories manage their issues -separately, so please be sure to check the right tracker for the repository to -which you would like to contribute. -</p> - -<p> -Most issues will be marked with one of the following workflow labels: -</p> - -<ul> - <li> - <b>NeedsInvestigation</b>: The issue is not fully understood - and requires analysis to understand the root cause. - </li> - <li> - <b>NeedsDecision</b>: the issue is relatively well understood, but the - Go team hasn't yet decided the best way to address it. - It would be better to wait for a decision before writing code. - If you are interested in working on an issue in this state, - feel free to "ping" maintainers in the issue's comments - if some time has passed without a decision. - </li> - <li> - <b>NeedsFix</b>: the issue is fully understood and code can be written - to fix it. - </li> -</ul> - -<p> -You can use GitHub's search functionality to find issues to help out with. Examples: -</p> - -<ul> - <li> - 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> - </li> - <li> - 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> - </li> - <li> - 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> - </li> - <li> - 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> - </li> -</ul> - -<h3 id="design">Open an issue for any new problem</h3> - -<p> -Excluding very trivial changes, all contributions should be connected -to an existing issue. -Feel free to open one and discuss your plans. -This process gives everyone a chance to validate the design, -helps prevent duplication of effort, -and ensures that the idea fits inside the goals for the language and tools. -It also checks that the design is sound before code is written; -the code review tool is not the place for high-level discussions. -</p> - -<p> -When planning work, please note that the Go project follows a <a -href="https://golang.org/wiki/Go-Release-Cycle">six-month development cycle</a> -for the main Go repository. The latter half of each cycle is a three-month -feature freeze during which only bug fixes and documentation updates are -accepted. New contributions can be sent during a feature freeze, but they will -not be merged until the freeze is over. The freeze applies to the entire main -repository as well as to the code in golang.org/x/... repositories that is -needed to build the binaries included in the release. See the lists of packages -vendored into -<a href="https://github.com/golang/go/blob/master/src/vendor/modules.txt">the standard library</a> -and the <a href="https://github.com/golang/go/blob/master/src/cmd/vendor/modules.txt"><code>go</code> command</a>. -</p> - -<p> -Significant changes to the language, libraries, or tools must go -through the -<a href="https://golang.org/s/proposal-process">change proposal process</a> -before they can be accepted. -</p> - -<p> -Sensitive security-related issues (only!) should be reported to <a href="mailto:security@golang.org">security@golang.org</a>. -</p> - -<h2 id="sending_a_change_github">Sending a change via GitHub</h2> - -<p> -First-time contributors that are already familiar with the -<a href="https://guides.github.com/introduction/flow/">GitHub flow</a> -are encouraged to use the same process for Go contributions. -Even though Go -maintainers use Gerrit for code review, a bot called Gopherbot has been created to sync -GitHub pull requests to Gerrit. -</p> - -<p> -Open a pull request as you normally would. -Gopherbot will create a corresponding Gerrit change and post a link to -it on your GitHub pull request; updates to the pull request will also -get reflected in the Gerrit change. -When somebody comments on the change, their comment will be also -posted in your pull request, so you will get a notification. -</p> - -<p> -Some things to keep in mind: -</p> - -<ul> -<li> -To update the pull request with new code, just push it to the branch; you can either -add more commits, or rebase and force-push (both styles are accepted). -</li> -<li> -If the request is accepted, all commits will be squashed, and the final -commit description will be composed by concatenating the pull request's -title and description. -The individual commits' descriptions will be discarded. -See <a href="#commit_messages">Writing good commit messages</a> for some -suggestions. -</li> -<li> -Gopherbot is unable to sync line-by-line codereview into GitHub: only the -contents of the overall comment on the request will be synced. -Remember you can always visit Gerrit to see the fine-grained review. -</li> -</ul> - -<h2 id="sending_a_change_gerrit">Sending a change via Gerrit</h2> - -<p> -It is not possible to fully sync Gerrit and GitHub, at least at the moment, -so we recommend learning Gerrit. -It's different but powerful and familiarity with it will help you understand -the flow. -</p> - -<h3 id="gerrit_overview">Overview</h3> - -<p> -This is an overview of the overall process: -</p> - -<ul> -<li> -<b>Step 1:</b> Clone the source code from <code>go.googlesource.com</code> and -make sure it's stable by compiling and testing it once. - -<p>If you're making a change to the -<a href="https://go.googlesource.com/go">main Go repository</a>:</p> - -<pre> -$ git clone https://go.googlesource.com/go -$ cd go/src -$ ./all.bash # compile and test -</pre> - -<p> -If you're making a change to one of the golang.org/x/... repositories -(<a href="https://go.googlesource.com/tools">golang.org/x/tools</a>, -in this example): -</p> - -<pre> -$ git clone https://go.googlesource.com/tools -$ cd tools -$ go test ./... # compile and test -</pre> -</li> - -<li> -<b>Step 2:</b> Prepare changes in a new branch, created from the master branch. -To commit the changes, use <code>git</code> <code>codereview</code> <code>change</code>; that -will create or amend a single commit in the branch. -<pre> -$ git checkout -b mybranch -$ [edit files...] -$ git add [files...] -$ git codereview change # create commit in the branch -$ [edit again...] -$ git add [files...] -$ git codereview change # amend the existing commit with new changes -$ [etc.] -</pre> -</li> - -<li> -<b>Step 3:</b> Test your changes, either by running the tests in the package -you edited or by re-running <code>all.bash</code>. - -<p>In the main Go repository:</p> -<pre> -$ ./all.bash # recompile and test -</pre> - -<p>In a golang.org/x/... repository:</p> -<pre> -$ go test ./... # recompile and test -</pre> -</li> - -<li> -<b>Step 4:</b> Send the changes for review to Gerrit using <code>git</code> -<code>codereview</code> <code>mail</code> (which doesn't use e-mail, despite the name). -<pre> -$ git codereview mail # send changes to Gerrit -</pre> -</li> - -<li> -<b>Step 5:</b> After a review, apply changes to the same single commit -and mail them to Gerrit again: -<pre> -$ [edit files...] -$ git add [files...] -$ git codereview change # update same commit -$ git codereview mail # send to Gerrit again -</pre> -</li> -</ul> - -<p> -The rest of this section describes these steps in more detail. -</p> - - -<h3 id="checkout_go">Step 1: Clone the source code</h3> - -<p> -In addition to a recent Go installation, you need to have a local copy of the source -checked out from the correct repository. -You can check out the Go source repo onto your local file system anywhere -you want as long as it's outside your <code>GOPATH</code>. -Clone from <code>go.googlesource.com</code> (not GitHub): -</p> - -<p>Main Go repository:</p> -<pre> -$ git clone https://go.googlesource.com/go -$ cd go -</pre> - -<p>golang.org/x/... repository</p> -(<a href="https://go.googlesource.com/tools">golang.org/x/tools</a> in this example): -<pre> -$ git clone https://go.googlesource.com/tools -$ cd tools -</pre> - -<h3 id="make_branch">Step 2: Prepare changes in a new branch</h3> - -<p> -Each Go change must be made in a separate branch, created from the master branch. -You can use -the normal <code>git</code> commands to create a branch and add changes to the -staging area: -</p> - -<pre> -$ git checkout -b mybranch -$ [edit files...] -$ git add [files...] -</pre> - -<p> -To commit changes, instead of <code>git commit</code>, use <code>git codereview change</code>. -</p> - -<pre> -$ git codereview change -(open $EDITOR) -</pre> - -<p> -You can edit the commit description in your favorite editor as usual. -The <code>git</code> <code>codereview</code> <code>change</code> command -will automatically add a unique Change-Id line near the bottom. -That line is used by Gerrit to match successive uploads of the same change. -Do not edit or delete it. -A Change-Id looks like this: -</p> - -<pre> -Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990 -</pre> - -<p> -The tool also checks that you've -run <code>go</code> <code>fmt</code> over the source code, and that -the commit message follows the <a href="#commit_messages">suggested format</a>. -</p> - -<p> -If you need to edit the files again, you can stage the new changes and -re-run <code>git</code> <code>codereview</code> <code>change</code>: each subsequent -run will amend the existing commit while preserving the Change-Id. -</p> - -<p> -Make sure that you always keep a single commit in each branch. -If you add more -commits by mistake, you can use <code>git</code> <code>rebase</code> to -<a href="https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github">squash them together</a> -into a single one. -</p> - - -<h3 id="testing">Step 3: Test your changes</h3> - -<p> -You've <a href="code.html">written and tested your code</a>, but -before sending code out for review, run <i>all the tests for the whole -tree</i> to make sure the changes don't break other packages or programs. -</p> - -<h4 id="test-gorepo">In the main Go repository</h4> - -<p>This can be done by running <code>all.bash</code>:</p> - -<pre> -$ cd go/src -$ ./all.bash -</pre> - -<p> -(To build under Windows use <code>all.bat</code>) -</p> - -<p> -After running for a while and printing a lot of testing output, the command should finish -by printing, -</p> - -<pre> -ALL TESTS PASSED -</pre> - -<p> -You can use <code>make.bash</code> instead of <code>all.bash</code> -to just build the compiler and the standard library without running the test suite. -Once the <code>go</code> tool is built, it will be installed as <code>bin/go</code> -under the directory in which you cloned the Go repository, and you can -run it directly from there. -See also -the section on how to <a href="#quick_test">test your changes quickly</a>. -</p> - -<h4 id="test-xrepo">In the golang.org/x/... repositories</h4> - -<p> -Run the tests for the entire repository -(<a href="https://go.googlesource.com/tools">golang.org/x/tools</a>, -in this example): -</p> - -<pre> -$ cd tools -$ go test ./... -</pre> - -<p> -If you're concerned about the build status, -you can check the <a href="https://build.golang.org">Build Dashboard</a>. -Test failures may also be caught by the TryBots in code review. -</p> - -<p> -Some repositories, like -<a href="https://go.googlesource.com/vscode-go">golang.org/x/vscode-go</a> will -have different testing infrastructures, so always check the documentation -for the repository in which you are working. The README file in the root of the -repository will usually have this information. -</p> - -<h3 id="mail">Step 4: Send changes for review</h3> - -<p> -Once the change is ready and tested over the whole tree, send it for review. -This is done with the <code>mail</code> sub-command which, despite its name, doesn't -directly mail anything; it just sends the change to Gerrit: -</p> - -<pre> -$ git codereview mail -</pre> - -<p> -Gerrit assigns your change a number and URL, which <code>git</code> <code>codereview</code> <code>mail</code> will print, something like: -</p> - -<pre> -remote: New Changes: -remote: https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments -</pre> - -<p> -If you get an error instead, check the -<a href="#troubleshooting_mail">Troubleshooting mail errors</a> section. -</p> - -<p> -If your change relates to an open GitHub issue and you have followed the <a href="#commit_messages"> -suggested commit message format</a>, the issue will be updated in a few minutes by a bot, -linking your Gerrit change to it in the comments. -</p> - - -<h3 id="revise">Step 5: Revise changes after a review</h3> - -<p> -Go maintainers will review your code on Gerrit, and you will get notifications via e-mail. -You can see the review on Gerrit and comment on them there. -You can also reply -<a href="https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email">using e-mail</a> -if you prefer. -</p> - -<p> -If you need to revise your change after the review, edit the files in -the same branch you previously created, add them to the Git staging -area, and then amend the commit with -<code>git</code> <code>codereview</code> <code>change</code>: -</p> - -<pre> -$ git codereview change # amend current commit -(open $EDITOR) -$ git codereview mail # send new changes to Gerrit -</pre> - -<p> -If you don't need to change the commit description, just save and exit from the editor. -Remember not to touch the special Change-Id line. -</p> - -<p> -Again, make sure that you always keep a single commit in each branch. -If you add more -commits by mistake, you can use <code>git rebase</code> to -<a href="https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github">squash them together</a> -into a single one. -</p> - -<h2 id="commit_messages">Good commit messages</h2> - -<p> -Commit messages in Go follow a specific set of conventions, -which we discuss in this section. -</p> - -<p> -Here is an example of a good one: -</p> - -<pre> -math: improve Sin, Cos and Tan precision for very large arguments - -The existing implementation has poor numerical properties for -large arguments, so use the McGillicutty algorithm to improve -accuracy above 1e10. - -The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm - -Fixes #159 -</pre> - -<h3 id="first_line">First line</h3> - -<p> -The first line of the change description is conventionally a short one-line -summary of the change, prefixed by the primary affected package. -</p> - -<p> -A rule of thumb is that it should be written so to complete the sentence -"This change modifies Go to _____." -That means it does not start with a capital letter, is not a complete sentence, -and actually summarizes the result of the change. -</p> - -<p> -Follow the first line by a blank line. -</p> - -<h3 id="main_content">Main content</h3> - -<p> -The rest of the description elaborates and should provide context for the -change and explain what it does. -Write in complete sentences with correct punctuation, just like -for your comments in Go. -Don't use HTML, Markdown, or any other markup language. -</p> - -<p> -Add any relevant information, such as benchmark data if the change -affects performance. -The <a href="https://godoc.org/golang.org/x/perf/cmd/benchstat">benchstat</a> -tool is conventionally used to format -benchmark data for change descriptions. -</p> - -<h3 id="ref_issues">Referencing issues</h3> - -<p> -The special notation "Fixes #12345" associates the change with issue 12345 in the -<a href="https://golang.org/issue/12345">Go issue tracker</a>. -When this change is eventually applied, the issue -tracker will automatically mark the issue as fixed. -</p> - -<p> -If the change is a partial step towards the resolution of the issue, -write "Updates #12345" instead. -This will leave a comment in the issue linking back to the change in -Gerrit, but it will not close the issue when the change is applied. -</p> - -<p> -If you are sending a change against a golang.org/x/... repository, you must use -the fully-qualified syntax supported by GitHub to make sure the change is -linked to the issue in the main repository, not the x/ repository. -Most issues are tracked in the main repository's issue tracker. -The correct form is "Fixes golang/go#159". -</p> - - -<h2 id="review">The review process</h2> - -<p> -This section explains the review process in detail and how to approach -reviews after a change has been mailed. -</p> - - -<h3 id="mistakes">Common beginner mistakes</h3> - -<p> -When a change is sent to Gerrit, it is usually triaged within a few days. -A maintainer will have a look and provide some initial review that for first-time -contributors usually focuses on basic cosmetics and common mistakes. -These include things like: -</p> - -<ul> -<li> -Commit message not following the <a href="#commit_messages">suggested -format</a>. -</li> - -<li> -The lack of a linked GitHub issue. -The vast majority of changes -require a linked issue that describes the bug or the feature that the change -fixes or implements, and consensus should have been reached on the tracker -before proceeding with it. -Gerrit reviews do not discuss the merit of the change, -just its implementation. -<br> -Only trivial or cosmetic changes will be accepted without an associated issue. -</li> - -<li> -Change sent during the freeze phase of the development cycle, when the tree -is closed for general changes. -In this case, -a maintainer might review the code with a line such as <code>R=go1.12</code>, -which means that it will be reviewed later when the tree opens for a new -development window. -You can add <code>R=go1.XX</code> as a comment yourself -if you know that it's not the correct time frame for the change. -</li> -</ul> - -<h3 id="trybots">Trybots</h3> - -<p> -After an initial reading of your change, maintainers will trigger trybots, -a cluster of servers that will run the full test suite on several different -architectures. -Most trybots complete in a few minutes, at which point a link will -be posted in Gerrit where you can see the results. -</p> - -<p> -If the trybot run fails, follow the link and check the full logs of the -platforms on which the tests failed. -Try to understand what broke, update your patch to fix it, and upload again. -Maintainers will trigger a new trybot run to see -if the problem was fixed. -</p> - -<p> -Sometimes, the tree can be broken on some platforms for a few hours; if -the failure reported by the trybot doesn't seem related to your patch, go to the -<a href="https://build.golang.org">Build Dashboard</a> and check if the same -failure appears in other recent commits on the same platform. -In this case, -feel free to write a comment in Gerrit to mention that the failure is -unrelated to your change, to help maintainers understand the situation. -</p> - -<h3 id="reviews">Reviews</h3> - -<p> -The Go community values very thorough reviews. -Think of each review comment like a ticket: you are expected to somehow "close" it -by acting on it, either by implementing the suggestion or convincing the -reviewer otherwise. -</p> - -<p> -After you update the change, go through the review comments and make sure -to reply to every one. -You can click the "Done" button to reply -indicating that you've implemented the reviewer's suggestion; otherwise, -click on "Reply" and explain why you have not, or what you have done instead. -</p> - -<p> -It is perfectly normal for changes to go through several round of reviews, -with one or more reviewers making new comments every time -and then waiting for an updated change before reviewing again. -This cycle happens even for experienced contributors, so -don't be discouraged by it. -</p> - -<h3 id="votes">Voting conventions</h3> - -<p> -As they near a decision, reviewers will make a "vote" on your change. -The Gerrit voting system involves an integer in the range -2 to +2: -</p> - -<ul> - <li> - <b>+2</b> The change is approved for being merged. - Only Go maintainers can cast a +2 vote. - </li> - <li> - <b>+1</b> The change looks good, but either the reviewer is requesting - minor changes before approving it, or they are not a maintainer and cannot - approve it, but would like to encourage an approval. - </li> - <li> - <b>-1</b> The change is not good the way it is but might be fixable. - A -1 vote will always have a comment explaining why the change is unacceptable. - </li> - <li> - <b>-2</b> The change is blocked by a maintainer and cannot be approved. - Again, there will be a comment explaining the decision. - </li> -</ul> - -<p> -At least two maintainers must approve of the change, and at least one -of those maintainers must +2 the change. -The second maintainer may cast a vote of Trust+1, meaning that the -change looks basically OK, but that the maintainer hasn't done the -detailed review required for a +2 vote. -</p> - -<h3 id="submit">Submitting an approved change</h3> - -<p> -After the code has been +2'ed and Trust+1'ed, an approver will -apply it to the master branch using the Gerrit user interface. -This is called "submitting the change". -</p> - -<p> -The two steps (approving and submitting) are separate because in some cases maintainers -may want to approve it but not to submit it right away (for instance, -the tree could be temporarily frozen). -</p> - -<p> -Submitting a change checks it into the repository. -The change description will include a link to the code review, -which will be updated with a link to the change -in the repository. -Since the method used to integrate the changes is Git's "Cherry Pick", -the commit hashes in the repository will be changed by -the submit operation. -</p> - -<p> -If your change has been approved for a few days without being -submitted, feel free to write a comment in Gerrit requesting -submission. -</p> - - -<h3 id="more_information">More information</h3> - -<p> -In addition to the information here, the Go community maintains a <a -href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page. -Feel free to contribute to this page as you learn more about the review process. -</p> - - - -<h2 id="advanced_topics">Miscellaneous topics</h2> - -<p> -This section collects a number of other comments that are -outside the issue/edit/code review/submit process itself. -</p> - - -<h3 id="copyright">Copyright headers</h3> - -<p> -Files in the Go repository don't list author names, both to avoid clutter -and to avoid having to keep the lists up to date. -Instead, your name will appear in the -<a href="https://golang.org/change">change log</a> and in the <a -href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a -href="/AUTHORS"><code>AUTHORS</code></a> file. -These files are automatically generated from the commit logs periodically. -The <a href="/AUTHORS"><code>AUTHORS</code></a> file defines who “The Go -Authors”—the copyright holders—are. -</p> - -<p> -New files that you contribute should use the standard copyright header: -</p> - -<pre> -// Copyright 2021 The Go Authors. All rights reserved. -// Use of this source code is governed by a BSD-style -// license that can be found in the LICENSE file. -</pre> - -<p> -(Use the current year if you're reading this in 2022 or beyond.) -Files in the repository are copyrighted the year they are added. -Do not update the copyright year on files that you change. -</p> - - - - -<h3 id="troubleshooting_mail">Troubleshooting mail errors</h3> - -<p> -The most common way that the <code>git</code> <code>codereview</code> <code>mail</code> -command fails is because the e-mail address in the commit does not match the one -that you used during <a href="#google_account">the registration process</a>. - -<br> -If you see something like... -</p> - -<pre> -remote: Processing changes: refs: 1, done -remote: -remote: ERROR: In commit ab13517fa29487dcf8b0d48916c51639426c5ee9 -remote: ERROR: author email address XXXXXXXXXXXXXXXXXXX -remote: ERROR: does not match your user account. -</pre> - -<p> -you need to configure Git for this repository to use the -e-mail address that you registered with. -To change the e-mail address to ensure this doesn't happen again, run: -</p> - -<pre> -$ git config user.email email@address.com -</pre> - -<p> -Then change the commit to use this alternative e-mail address with this command: -</p> - -<pre> -$ git commit --amend --author="Author Name <email@address.com>" -</pre> - -<p> -Then retry by running: -</p> - -<pre> -$ git codereview mail -</pre> - - -<h3 id="quick_test">Quickly testing your changes</h3> - -<p> -Running <code>all.bash</code> for every single change to the code tree -is burdensome. -Even though it is strongly suggested to run it before -sending a change, during the normal development cycle you may want -to compile and test only the package you are developing. -</p> - -<ul> -<li> -In general, you can run <code>make.bash</code> instead of <code>all.bash</code> -to only rebuild the Go tool chain without running the whole test suite. -Or you -can run <code>run.bash</code> to only run the whole test suite without rebuilding -the tool chain. -You can think of <code>all.bash</code> as <code>make.bash</code> -followed by <code>run.bash</code>. -</li> - -<li> -In this section, we'll call the directory into which you cloned the Go repository <code>$GODIR</code>. -The <code>go</code> tool built by <code>$GODIR/src/make.bash</code> will be installed -in <code>$GODIR/bin/go</code> and you -can invoke it to test your code. -For instance, if you -have modified the compiler and you want to test how it affects the -test suite of your own project, just run <code>go</code> <code>test</code> -using it: - -<pre> -$ cd <MYPROJECTDIR> -$ $GODIR/bin/go test -</pre> -</li> - -<li> -If you're changing the standard library, you probably don't need to rebuild -the compiler: you can just run the tests for the package you've changed. -You can do that either with the Go version you normally use, or -with the Go compiler built from your clone (which is -sometimes required because the standard library code you're modifying -might require a newer version than the stable one you have installed). - -<pre> -$ cd $GODIR/src/crypto/sha1 -$ [make changes...] -$ $GODIR/bin/go test . -</pre> -</li> - -<li> -If you're modifying the compiler itself, you can just recompile -the <code>compile</code> tool (which is the internal binary invoked -by <code>go</code> <code>build</code> to compile each single package). -After that, you will want to test it by compiling or running something. - -<pre> -$ cd $GODIR/src -$ [make changes...] -$ $GODIR/bin/go install cmd/compile -$ $GODIR/bin/go build [something...] # test the new compiler -$ $GODIR/bin/go run [something...] # test the new compiler -$ $GODIR/bin/go test [something...] # test the new compiler -</pre> - -The same applies to other internal tools of the Go tool chain, -such as <code>asm</code>, <code>cover</code>, <code>link</code>, and so on. -Just recompile and install the tool using <code>go</code> -<code>install</code> <code>cmd/<TOOL></code> and then use -the built Go binary to test it. -</li> - -<li> -In addition to the standard per-package tests, there is a top-level -test suite in <code>$GODIR/test</code> that contains -several black-box and regression tests. -The test suite is run -by <code>all.bash</code> but you can also run it manually: - -<pre> -$ cd $GODIR/test -$ $GODIR/bin/go run run.go -</pre> -</ul> - - -<h3 id="cc">Specifying a reviewer / CCing others</h3> - -<p> -Unless explicitly told otherwise, such as in the discussion leading -up to sending in the change, it's better not to specify a reviewer. -All changes are automatically CC'ed to the -<a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a> -mailing list. -If this is your first ever change, there may be a moderation -delay before it appears on the mailing list, to prevent spam. -</p> - -<p> -You can specify a reviewer or CC interested parties -using the <code>-r</code> or <code>-cc</code> options. -Both accept a comma-separated list of e-mail addresses: -</p> - -<pre> -$ git codereview mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com -</pre> - - -<h3 id="sync">Synchronize your client</h3> - -<p> -While you were working, others might have submitted changes to the repository. -To update your local branch, run -</p> - -<pre> -$ git codereview sync -</pre> - -<p> -(Under the covers this runs -<code>git</code> <code>pull</code> <code>-r</code>.) -</p> - - -<h3 id="download">Reviewing code by others</h3> - -<p> -As part of the review process reviewers can propose changes directly (in the -GitHub workflow this would be someone else attaching commits to a pull request). - -You can import these changes proposed by someone else into your local Git repository. -On the Gerrit review page, click the "Download ▼" link in the upper right -corner, copy the "Checkout" command and run it from your local Git repo. -It will look something like this: -</p> - -<pre> -$ git fetch https://go.googlesource.com/review refs/changes/21/13245/1 && git checkout FETCH_HEAD -</pre> - -<p> -To revert, change back to the branch you were working in. -</p> - - -<h3 id="git-config">Set up git aliases</h3> - -<p> -The <code>git-codereview</code> command can be run directly from the shell -by typing, for instance, -</p> - -<pre> -$ git codereview sync -</pre> - -<p> -but it is more convenient to set up aliases for <code>git-codereview</code>'s own -subcommands, so that the above becomes, -</p> - -<pre> -$ git sync -</pre> - -<p> -The <code>git-codereview</code> subcommands have been chosen to be distinct from -Git's own, so it's safe to define these aliases. -To install them, copy this text into your -Git configuration file (usually <code>.gitconfig</code> in your home directory): -</p> - -<pre> -[alias] - change = codereview change - gofmt = codereview gofmt - mail = codereview mail - pending = codereview pending - submit = codereview submit - sync = codereview sync -</pre> - - -<h3 id="multiple_changes">Sending multiple dependent changes</h3> - -<p> -Advanced users may want to stack up related commits in a single branch. -Gerrit allows for changes to be dependent on each other, forming such a dependency chain. -Each change will need to be approved and submitted separately but the dependency -will be visible to reviewers. -</p> - -<p> -To send out a group of dependent changes, keep each change as a different commit under -the same branch, and then run: -</p> - -<pre> -$ git codereview mail HEAD -</pre> - -<p> -Make sure to explicitly specify <code>HEAD</code>, which is usually not required when sending -single changes. More details can be found in the <a href="https://pkg.go.dev/golang.org/x/review/git-codereview?tab=doc#hdr-Multiple_Commit_Work_Branches">git-codereview documentation</a>. -</p> |