diff options
Diffstat (limited to 'go/golang/go/doc/contribute.html')
| -rw-r--r-- | go/golang/go/doc/contribute.html | 1213 |
1 files changed, 1213 insertions, 0 deletions
diff --git a/go/golang/go/doc/contribute.html b/go/golang/go/doc/contribute.html new file mode 100644 index 00000000..5dc8a004 --- /dev/null +++ b/go/golang/go/doc/contribute.html @@ -0,0 +1,1213 @@ +<!--{ + "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>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 +on "Generate Password" (top right), 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 this 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. +</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 $GOPATH/bin 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>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> +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 on 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>. +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. +</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 help you understand the flow. +</p> + +<h3>Overview</h3> + +<p> +This is an overview of the overall process: +</p> + +<ul> +<li> +<b>Step 1:</b> Clone the Go source code from go.googlesource.com +and make sure it's stable by compiling and testing it once: +<pre> +$ git clone https://go.googlesource.com/go +$ cd go/src +$ ./all.bash # 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, re-running <code>all.bash</code>. +<pre> +$ ./all.bash # 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 Go 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>. +Either clone from +<code>go.googlesource.com</code> or from GitHub: +</p> + +<pre> +$ git clone https://github.com/golang/go # or https://go.googlesource.com/go +$ cd go +</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> + +<pre> +$ cd go/src +$ ./all.bash +</pre> + +<p> +(To build under Windows use <code>all.bat</code>; this also requires +setting the environment variable <code>GOROOT_BOOTSTRAP</code> to the +directory holding the Go tree for the bootstrap compiler.) +</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> + +<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>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>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/tools/cmd/benchcmp">benchcmp</a> +tool is conventionally used to format +benchmark data for change descriptions. +</p> + +<h3>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, +uses the notation "Updates #12345". +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 subrepository, 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 subrepository. +All 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> + +<h3 id="submit">Submitting an approved change</h3> + +<p> +After the code has been +2'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 2018 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 2019 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/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/hash/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="subrepos">Contributing to subrepositories (golang.org/x/...)</h3> + +<p> +If you are contributing a change to a subrepository, obtain the +Go package using <code>go get</code>. +For example, to contribute +to <code>golang.org/x/oauth2</code>, check out the code by running: +</p> + +<pre> +$ go get -d golang.org/x/oauth2/... +</pre> + +<p> +Then, change your directory to the package's source directory +(<code>$GOPATH/src/golang.org/x/oauth2</code>), and follow the +normal contribution flow. +</p> + + +<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. +</p> |