| <!--{ |
| "Title": "Contribution Guide", |
| "Template": true, |
| "Breadcrumb": true |
| }--> |
| |
| <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="/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 install golang.org/x/review/git-codereview@latest</code> |
| </li> |
| </ul> |
| |
| <p> |
| If you prefer, there is an automated tool that walks through these steps. |
| Just run: |
| </p> |
| |
| <pre> |
| $ go install golang.org/x/tools/cmd/go-contrib-init@latest |
| $ 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. |
| </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 install golang.org/x/review/git-codereview@latest |
| </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="/issue/new">filing |
| a new issue</a> or by claiming |
| an <a href="/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/... repositories. |
| 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="/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 suggested change: <a href="https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+%28%22golang.org%2Fcl%22+OR+%22go.dev%2Fcl%22%29"><code>is:issue is:open label:NeedsFix ("golang.org/cl" OR "go.dev/cl")</code></a> |
| </li> |
| <li> |
| Issues that need a fix and do not have a suggested change: <a href="https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+%22golang.org%2Fcl%22+NOT+%22go.dev%2Fcl%22"><code>is:issue is:open label:NeedsFix NOT "golang.org/cl" NOT "go.dev/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="/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 |
| (which includes API changes in the main repo and all golang.org/x repos, |
| as well as command-line changes to the <code>go</code> command) |
| must go |
| through the |
| <a href="/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="/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 apply a Code-Review “vote” to your change. |
| There are two possible votes: |
| </p> |
| |
| <ul> |
| <li> |
| <b>+2</b> The change is approved for being merged. |
| Only Go maintainers (also referred to as “approvers”) 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> |
| </ul> |
| |
| <p> |
| To be submitted, a change must have a Code-Review +2 from a maintainer. |
| </p> |
| |
| <p> |
| Maintainers can also apply a Hold +1 vote to the change, |
| to mark a change that should not be submitted now |
| (for example, because the <a href="/s/proposal-process">proposal review</a> |
| for new API in the change has not completed). |
| </p> |
| |
| <p> |
| To be submitted, a change must not have any Hold +1 votes from a maintainer. |
| </p> |
| |
| <p> |
| Finally, to be submitted, a change must have the involvement of two Google employees, |
| either as the uploader of the change or as a reviewer voting at least Code-Review +1. |
| This requirement is for compliance and supply chain security reasons. |
| </p> |
| |
| <h3 id="submit">Submitting an approved change</h3> |
| |
| <p> |
| When a change is ready, a maintainer will submit the change, |
| which adds it as a commit to the Gerrit repository. |
| </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="/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="/change">change log</a>. |
| </p> |
| |
| <p> |
| New files that you contribute should use the standard copyright header: |
| </p> |
| |
| <pre> |
| // Copyright {{now.UTC.Year}} 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> |
| 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>$GOROOT</code>. |
| The <code>go</code> tool built by <code>$GOROOT/src/make.bash</code> will be installed |
| in <code>$GOROOT/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> |
| $ $GOROOT/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 $GOROOT/src/crypto/sha1 |
| $ [make changes...] |
| $ $GOROOT/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 $GOROOT/src |
| $ [make changes...] |
| $ $GOROOT/bin/go install cmd/compile |
| $ $GOROOT/bin/go build [something...] # test the new compiler |
| $ $GOROOT/bin/go run [something...] # test the new compiler |
| $ $GOROOT/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>$GOROOT/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> |
| $ $GOROOT/bin/go test cmd/internal/testdir |
| </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). |
| |
| Gerrit provides access to commands that will help you import changes proposed |
| by another developer so you can review/test them locally. From the Gerrit page |
| for the CL you want to import, open the "⋮" menu, click the "Download patch" link. |
| Depending on your preferred git workflow, choose the appropriate command. The options |
| 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> |