1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213 |
- <!--{
- "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 the gear icon (top right), then on "Obtain password", 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 it will 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 <code>go.googlesource.com</code>
- 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>.
- Clone from <code>go.googlesource.com</code> (not GitHub):
- </p>
- <pre>
- $ git clone 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/perf/cmd/benchstat">benchstat</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 2019 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 2020 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>
|