github.com/mattn/go@v0.0.0-20171011075504-07f7db3ea99f/doc/contribute.html (about)

     1  <!--{
     2  	"Title": "Contribution Guide"
     3  }-->
     4  
     5  <p>
     6  The Go project welcomes all contributors. The process of contributing
     7  to the Go project may be different than many projects you are used to.
     8  This document is intended as a guide to help you through the contribution
     9  process. This guide assumes you have a basic understanding of Git and Go.
    10  </p>
    11  
    12  <p>
    13  (Note that the <code>gccgo</code> frontend lives elsewhere;
    14  see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
    15  </p>
    16  
    17  <p>
    18  Sensitive security-related issues should be reported to <a href="mailto:security@golang.org">security@golang.org</a>.
    19  </p>
    20  
    21  <h1 id="contributor">Becoming a contributor</h1>
    22  
    23  <p>
    24  Before you can contribute to the Go project you need to setup a few prerequisites.
    25  The Go project uses <a href="https://www.gerritcodereview.com/">Gerrit</a>, an open
    26  source online tool, to perform all code reviews.
    27  Gerrit uses your email address as a unique identifier.
    28  The Go project contributing flow is currently configured to work only with Google Accounts.
    29  You must go through the following process <em>prior to contributing</em>.
    30  You only need to do this once per Google Account.
    31  </p>
    32  
    33  <h2 id="go-contrib-init">Automatically set up &amp; diagnose your development environment</h3>
    34  <p>
    35    The <code>go-contrib-init</code> tool configures and debugs your Go
    36    development environment, automatically performing many of the steps
    37    on this page, or telling you what you need to do next. If you wish
    38    to use it, run:
    39  </p>
    40  
    41  <pre>
    42  $ go get -u golang.org/x/tools/cmd/go-contrib-init
    43  $ cd /code/to/edit
    44  $ go-contrib-init
    45  </pre>
    46  
    47  <p>
    48    The tool will either set things up, tell you that everything is
    49    configured, or tell you what steps you need to do manually.
    50  </p>
    51  
    52  <h2 id="auth">Configure Git to use Gerrit</h2>
    53  <p>
    54  You'll need a web browser and a command line terminal.
    55  You should already have Git installed.
    56  </p>
    57  
    58  <p>
    59  Gerrit uses Google Accounts for authentication.
    60  If you don't have a Google Account, you can create an account which
    61  <a href="https://www.google.com/accounts/NewAccount">includes
    62  a new Gmail email account</a> or create an account associated
    63  <a href="https://accounts.google.com/SignUpWithoutGmail">with your existing
    64  email address</a>.
    65  </p>
    66  
    67  <h3>Step 1: Sign in to googlesource and generate a password</h3>
    68  
    69  <p>
    70  Visit <a href="https://go.googlesource.com">go.googlesource.com</a>
    71  and click on "Generate Password" in the page's top right menu bar.
    72  You will be redirected to accounts.google.com to sign in.
    73  </p>
    74  
    75  <h3>Step 2: Run the provided script</h3>
    76  <p>
    77  After signing in, you are taken to a page on go.googlesource.com with the title "Configure Git".
    78  This page contains a personalized script which when run locally will configure git
    79  to have your unique authentication key.
    80  This key is paired with one generated server side similar to how ssh keys work.
    81  </p>
    82  
    83  <p>
    84  Copy and run this script locally in your command line terminal.
    85  (On a Windows computer using cmd you should instead follow the instructions
    86  in the yellow box to run the command. If you are using git-bash use the same
    87  script as *nix.)
    88  </p>
    89  
    90  <p>
    91  Your secret authentication token is now in a <code>.gitcookies</code> file
    92  and Git is configured to use this file.
    93  </p>
    94  
    95  <h3 id="gerrit">Step 3: Register with Gerrit</h3>
    96  
    97  <p>
    98  Now that you have your authentication token, you need to register your
    99  account with Gerrit.
   100  To do this, visit <a href="https://go-review.googlesource.com/login/">
   101  go-review.googlesource.com/login/</a>.
   102  Sign in using the same Google Account you used above.
   103  </p>
   104  
   105  <h2 id="cla">Contributor License Agreement</h2>
   106  
   107  <h3 id="which_cla">Which CLA</h3>
   108  <p>
   109  Before sending your first change to the Go project
   110  you must have completed one of the following two CLAs.
   111  Which CLA you should sign depends on who owns the copyright to your work.
   112  </p>
   113  
   114  <ul>
   115  <li>
   116  If you are the copyright holder, you will need to agree to the
   117  <a href="https://developers.google.com/open-source/cla/individual">individual
   118  contributor license agreement</a>, which can be completed online.
   119  </li>
   120  <li>
   121  If your organization is the copyright holder, the organization
   122  will need to agree to the
   123  <a href="https://developers.google.com/open-source/cla/corporate">corporate
   124  contributor license agreement</a>.<br>
   125  </li>
   126  </ul>
   127  
   128  <p>
   129  <i>If the copyright holder for your contribution has already completed the
   130  agreement in connection with another Google open source project,
   131  it does not need to be completed again.</i>
   132  </p>
   133  
   134  <h3 id="signing_cla">Completing the CLA</h3>
   135  
   136  <p>
   137  You can see your currently signed agreements and sign new ones through the Gerrit
   138  interface.
   139  To do this, <a href="https://go-review.googlesource.com/login/">Log into Gerrit</a>,
   140  then visit the <a href="https://go-review.googlesource.com/settings/agreements">Agreements</a>
   141  page.
   142  If you do not have a signed agreement listed there, you can create one
   143  by clicking "New Contributor Agreement" and following the steps.
   144  </p>
   145  
   146  <p>
   147  If the copyright holder for the code you are submitting changes &mdash; for example,
   148  if you start contributing code on behalf of a new company &mdash; please send email
   149  to golang-dev and let us know, so that we can make sure an appropriate agreement is
   150  completed and update the <code>AUTHORS</code> file.
   151  </p>
   152  
   153  <span id="Code_review"></span>
   154  <h1 id="prepare_dev_env">Preparing a Development Environment for Contributing</h1>
   155  
   156  <h2 id="git-codereview">Setting up Git for submission to Gerrit</h2>
   157  <p>
   158  Changes to Go must be reviewed before they are accepted, no matter who makes the change.
   159  A custom git command called <code>git-codereview</code>, discussed below,
   160  helps manage the code review process through a Google-hosted
   161  <a href="https://go-review.googlesource.com/">instance</a> of Gerrit.
   162  </p>
   163  
   164  <h3 id="git-codereview_install">Install the git-codereview command</h3>
   165  <p>
   166  Install the <code>git-codereview</code> command by running,
   167  </p>
   168  
   169  <pre>
   170  $ go get -u golang.org/x/review/git-codereview
   171  </pre>
   172  
   173  <p>
   174  Make sure <code>git-codereview</code> is installed in your shell path, so that the
   175  <code>git</code> command can find it. Check that
   176  </p>
   177  
   178  <pre>
   179  $ git codereview help
   180  </pre>
   181  
   182  <p>
   183  prints help text, not an error.
   184  </p>
   185  
   186  <p>
   187  On Windows, when using git-bash you must make sure that
   188  <code>git-codereview.exe</code> is in your git exec-path.
   189  Run <code>git --exec-path</code> to discover the right location then create a
   190  symbolic link or simply copy the executible from $GOPATH/bin to this directory.
   191  </p>
   192  
   193  <p>
   194  <b>Note to Git aficionados:</b>
   195  The <code>git-codereview</code> command is not required to
   196  upload and manage Gerrit code reviews.
   197  For those who prefer plain Git, the text below gives the Git equivalent of
   198  each git-codereview command.
   199  </p>
   200  
   201  <p>
   202  If you do use plain Git, note that you still need the commit hooks that the
   203  git-codereview command configures; those hooks add a Gerrit
   204  <code>Change-Id</code> line to the commit message and check that all Go source
   205  files have been formatted with gofmt.
   206  Even if you intend to use plain Git for
   207  daily work, install the hooks in a new Git checkout by running
   208  <code>git-codereview</code> <code>hooks</code>.
   209  </p>
   210  
   211  <p>
   212  The workflow described below assumes a single change per branch.
   213  It is also possible to prepare a sequence of (usually related) changes in a single branch.
   214  See the <a href="https://golang.org/x/review/git-codereview">git-codereview documentation</a> for details.
   215  </p>
   216  
   217  <h3 id="git-config">Set up git aliases</h3>
   218  
   219  <p>
   220  The <code>git-codereview</code> command can be run directly from the shell
   221  by typing, for instance,
   222  </p>
   223  
   224  <pre>
   225  $ git codereview sync
   226  </pre>
   227  
   228  <p>
   229  but it is more convenient to set up aliases for <code>git-codereview</code>'s own
   230  subcommands, so that the above becomes,
   231  </p>
   232  
   233  <pre>
   234  $ git sync
   235  </pre>
   236  
   237  <p>
   238  The <code>git-codereview</code> subcommands have been chosen to be distinct from
   239  Git's own, so it's safe to do so.
   240  </p>
   241  
   242  <p>
   243  The aliases are optional, but in the rest of this document we will assume
   244  they are installed.
   245  To install them, copy this text into your Git configuration file
   246  (usually <code>.gitconfig</code> in your home directory):
   247  </p>
   248  
   249  <pre>
   250  [alias]
   251  	change = codereview change
   252  	gofmt = codereview gofmt
   253  	mail = codereview mail
   254  	pending = codereview pending
   255  	submit = codereview submit
   256  	sync = codereview sync
   257  </pre>
   258  
   259  <span id="help"></span>
   260  <h3 id="understanding_git-codereview">Understanding the git-codereview command</h3>
   261  
   262  <p>After installing the <code>git-codereview</code> command, you can run</p>
   263  
   264  <pre>
   265  $ git codereview help
   266  </pre>
   267  
   268  <p>
   269  to learn more about its commands.
   270  You can also read the <a href="https://godoc.org/golang.org/x/review/git-codereview">command documentation</a>.
   271  </p>
   272  
   273  
   274  <h1 id="making_a_contribution">Making a Contribution</h1>
   275  
   276  <h2 id="Design">Discuss your design</h2>
   277  
   278  <p>
   279  The project welcomes submissions but please let everyone know what
   280  you're working on if you want to change or add to the Go repositories.
   281  </p>
   282  
   283  <p>
   284  Before undertaking to write something new for the Go project,
   285  please <a href="https://golang.org/issue/new">file an issue</a>
   286  (or claim an <a href="https://golang.org/issues">existing issue</a>).
   287  Significant changes must go through the
   288  <a href="https://golang.org/s/proposal-process">change proposal process</a>
   289  before they can be accepted.
   290  </p>
   291  
   292  <p>
   293  This process gives everyone a chance to validate the design,
   294  helps prevent duplication of effort,
   295  and ensures that the idea fits inside the goals for the language and tools.
   296  It also checks that the design is sound before code is written;
   297  the code review tool is not the place for high-level discussions.
   298  </p>
   299  
   300  <p>
   301  When planning work, please note that the Go project follows a <a
   302  href="https://golang.org/wiki/Go-Release-Cycle">six-month development cycle</a>.
   303  The latter half of each cycle is a three-month feature freeze during
   304  which only bug fixes and doc updates are accepted. New contributions can be
   305  sent during a feature freeze but will not be accepted until the freeze thaws.
   306  </p>
   307  
   308  <h2 id="making_a_change">Making a change</h2>
   309  
   310  <h3 id="checkout_go">Getting Go Source</h3>
   311  <p>
   312  First you need to have a local copy of the source checked out from the correct
   313  repository.
   314  As Go builds Go you will also likely need to have a working version
   315  of Go installed (some documentation changes may not need this).
   316  This should be a recent version of Go and can be obtained via any package or
   317  binary distribution or you can build it from source.
   318  </p>
   319  
   320  <p>
   321  You should checkout the Go source repo anywhere you want as long as it's
   322  outside of your $GOPATH.
   323  Go to a directory where you want the source to appear and run the following
   324  command in a terminal.
   325  </p>
   326  
   327  <pre>
   328  $ git clone https://go.googlesource.com/go
   329  $ cd go
   330  </pre>
   331  
   332  <h3 id="master">Contributing to the main Go tree</h3>
   333  
   334  <p>
   335  Most Go installations use a release branch, but new changes should
   336  only be made based on the master branch. <br>
   337  (They may be applied later to a release branch as part of the release process,
   338  but most contributors won't do this themselves.)
   339  Before making a change, make sure you start on the master branch:
   340  </p>
   341  
   342  <pre>
   343  $ git checkout master
   344  $ git sync
   345  </pre>
   346  
   347  <p>
   348  (In Git terms, <code>git</code> <code>sync</code> runs
   349  <code>git</code> <code>pull</code> <code>-r</code>.)
   350  </p>
   351  
   352  <h3 id="subrepos">Contributing to subrepositories (golang.org/x/...)</h3>
   353  
   354  <p>
   355  If you are contributing a change to a subrepository, obtain the
   356  Go package using <code>go get</code>. For example, to contribute
   357  to <code>golang.org/x/oauth2</code>, check out the code by running:
   358  </p>
   359  
   360  <pre>
   361  $ go get -d golang.org/x/oauth2/...
   362  </pre>
   363  
   364  <p>
   365  Then, change your directory to the package's source directory
   366  (<code>$GOPATH/src/golang.org/x/oauth2</code>).
   367  </p>
   368  
   369  <h3 id="change">Make your changes</h3>
   370  
   371  <p>
   372  The entire checked-out tree is editable.
   373  Make your changes as you see fit ensuring that you create appropriate
   374  tests along with your changes. Test your changes as you go.
   375  </p>
   376  
   377  <h3 id="copyright">Copyright</h3>
   378  
   379  <p>
   380  Files in the Go repository don't list author names, both to avoid clutter
   381  and to avoid having to keep the lists up to date.
   382  Instead, your name will appear in the
   383  <a href="https://golang.org/change">change log</a> and in the <a
   384  href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a
   385  href="/AUTHORS"><code>AUTHORS</code></a> file.
   386  These files are automatically generated from the commit logs perodically.
   387  The <a href="/AUTHORS"><code>AUTHORS</code></a> file defines who &ldquo;The Go
   388  Authors&rdquo;&mdash;the copyright holders&mdash;are.
   389  </p>
   390  
   391  <p>New files that you contribute should use the standard copyright header:</p>
   392  
   393  <pre>
   394  // Copyright 2017 The Go Authors. All rights reserved.
   395  // Use of this source code is governed by a BSD-style
   396  // license that can be found in the LICENSE file.
   397  </pre>
   398  
   399  <p>
   400  Files in the repository are copyright the year they are added.
   401  Do not update the copyright year on files that you change.
   402  </p>
   403  
   404  <h3 id="commit_changes">Commit your changes</h3>
   405  
   406  <p>
   407  Once you have edited files, you must tell Git that they have been modified.
   408  You must also tell Git about any files that are added, removed, or renamed files.
   409  These operations are done with the usual Git commands,
   410  <code>git</code> <code>add</code>,
   411  <code>git</code> <code>rm</code>,
   412  and
   413  <code>git</code> <code>mv</code>.
   414  </p>
   415  
   416  <p>
   417  Once you have the changes queued up, you will want to commit them.
   418  In the Go contribution workflow this is done with a <code>git</code>
   419  <code>change</code> command, which creates a local branch and commits the changes
   420  directly to that local branch.
   421  </p>
   422  
   423  <pre>
   424  $ git change <i>&lt;branch&gt;</i>
   425  </pre>
   426  
   427  <p>
   428  The name <i>&lt;branch&gt;</i> is an arbitrary one you choose to identify the
   429  local branch containing your changes and will not be used elsewhere.
   430  This is an offline operation and nothing will be sent to the server yet.
   431  </p>
   432  
   433  <p>
   434  (In Git terms, <code>git</code> <code>change</code> <code>&lt;branch&gt;</code>
   435  runs <code>git</code> <code>checkout</code> <code>-b</code> <code>branch</code>,
   436  then <code>git</code> <code>branch</code> <code>--set-upstream-to</code> <code>origin/master</code>,
   437  then <code>git</code> <code>commit</code>.)
   438  </p>
   439  
   440  <p>
   441  As the <code>git</code> <code>commit</code> is the final step, Git will open an
   442  editor to ask for a commit message. (It uses the editor named by
   443  the <code>$EDITOR</code> environment variable,
   444  <code>vi</code> by default.)
   445  
   446  The file will look like:
   447  </p>
   448  
   449  <pre>
   450  
   451  # Please enter the commit message for your changes. Lines starting
   452  # with '#' will be ignored, and an empty message aborts the commit.
   453  # On branch foo
   454  # Changes not staged for commit:
   455  #	modified:   editedfile.go
   456  #
   457  </pre>
   458  
   459  <p>
   460  At the beginning of this file is a blank line; replace it
   461  with a thorough description of your change.
   462  The first line of the change description is conventionally a one-line
   463  summary of the change, prefixed by the primary affected package,
   464  and is used as the subject for code review email.
   465  It should complete the sentence "This change modifies Go to _____."
   466  The rest of the description elaborates and should provide context for the
   467  change and explain what it does.
   468  Write in complete sentences with correct punctuation, just like
   469  for your comments in Go.
   470  If there is a helpful reference, mention it here.
   471  If you've fixed an issue, reference it by number with a # before it.
   472  </p>
   473  
   474  <p>
   475  After editing, the template might now read:
   476  </p>
   477  
   478  <pre>
   479  math: improve Sin, Cos and Tan precision for very large arguments
   480  
   481  The existing implementation has poor numerical properties for
   482  large arguments, so use the McGillicutty algorithm to improve
   483  accuracy above 1e10.
   484  
   485  The algorithm is described at http://wikipedia.org/wiki/McGillicutty_Algorithm
   486  
   487  Fixes #159
   488  
   489  # Please enter the commit message for your changes. Lines starting
   490  # with '#' will be ignored, and an empty message aborts the commit.
   491  # On branch foo
   492  # Changes not staged for commit:
   493  #	modified:   editedfile.go
   494  #
   495  </pre>
   496  
   497  <p>
   498  The commented section of the file lists all the modified files in your client.
   499  It is best to keep unrelated changes in different commits,
   500  so if you see a file listed that should not be included, abort
   501  the command and move that file to a different branch.
   502  </p>
   503  
   504  <p>
   505  The special notation "Fixes #159" associates the change with issue 159 in the
   506  <a href="https://golang.org/issue/159">Go issue tracker</a>.
   507  When this change is eventually applied, the issue
   508  tracker will automatically mark the issue as fixed.
   509  (There are several such conventions, described in detail in the
   510  <a href="https://help.github.com/articles/closing-issues-via-commit-messages/">GitHub Issue Tracker documentation</a>.)
   511  </p>
   512  
   513  <p>
   514  Once you have finished writing the commit message,
   515  save the file and exit the editor.
   516  </p>
   517  
   518  <p>
   519  You must have the $EDITOR environment variable set properly and working properly (exiting cleanly)
   520  for this operation to succeed.
   521  If you run into any issues at this step, it's likely your editor isn't exiting cleanly.
   522  Try setting a different editor in your $EDITOR environment variable.
   523  </p>
   524  
   525  <p>
   526  If you wish to do more editing, re-stage your changes using
   527  <code>git</code> <code>add</code>, and then run
   528  </p>
   529  
   530  <pre>
   531  $ git change
   532  </pre>
   533  
   534  <p>
   535  to update the change description and incorporate the staged changes.
   536  The change description contains a <code>Change-Id</code> line near the bottom,
   537  added by a Git commit hook during the initial
   538  <code>git</code> <code>change</code>.
   539  That line is used by Gerrit to match successive uploads of the same change.
   540  Do not edit or delete it.
   541  </p>
   542  
   543  <p>
   544  (In Git terms, <code>git</code> <code>change</code> with no branch name
   545  runs <code>git</code> <code>commit</code> <code>--amend</code>.)
   546  </p>
   547  
   548  <h3 id="Testing">Testing</h3>
   549  
   550  <p>
   551  You've <a href="code.html">written and tested your code</a>, but
   552  before sending code out for review, run all the tests for the whole
   553  tree to make sure the changes don't break other packages or programs:
   554  </p>
   555  
   556  <pre>
   557  $ cd go/src
   558  $ ./all.bash
   559  </pre>
   560  
   561  <p>
   562  (To build under Windows use <code>all.bat</code>.)
   563  </p>
   564  
   565  <p>
   566  After running for a while, the command should print
   567  </p>
   568  
   569  <pre>
   570  "ALL TESTS PASSED".
   571  </pre>
   572  
   573  <h3 id="mail">Send the change for review</h3>
   574  
   575  <p>
   576  Once the change is ready, send it for review.
   577  This is similar to a <code>git push</code> in a GitHub style workflow.
   578  This is done via the mail alias setup earlier which despite its name, doesn't
   579  directly mail anything, it simply sends the change to Gerrit via git push.
   580  </p>
   581  
   582  <pre>
   583  $ git mail
   584  </pre>
   585  
   586  <p>
   587  (In Git terms, <code>git</code> <code>mail</code> pushes the local committed
   588  changes to Gerrit using <code>git</code> <code>push</code> <code>origin</code>
   589  <code>HEAD:refs/for/master</code>.)
   590  </p>
   591  
   592  <p>
   593  If your change relates to an open issue, please add a comment to the issue
   594  announcing your proposed fix, including a link to your change.
   595  </p>
   596  
   597  <p>
   598  The code review server assigns your change an issue number and URL,
   599  which <code>git</code> <code>mail</code> will print, something like:
   600  </p>
   601  
   602  <pre>
   603  remote: New Changes:
   604  remote:   https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments
   605  </pre>
   606  
   607  <h3>Troubleshooting</h3>
   608  
   609  <p>
   610  The most common way that the <code>git mail</code> command fails is because the
   611  email address used has not gone through the setup above.
   612  <br>
   613  If you see something like...
   614  </p>
   615  
   616  <pre>
   617  remote: Processing changes: refs: 1, done
   618  remote:
   619  remote: ERROR:  In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
   620  remote: ERROR:  author email address XXXXXXXXXXXXXXXXXXX
   621  remote: ERROR:  does not match your user account.
   622  </pre>
   623  
   624  <p>
   625  You need to either add the email address listed to the CLA or set this repo to use
   626  another email address already approved.
   627  </p>
   628  
   629  <p>
   630  First let's change the email address for this repo so this doesn't happen again.
   631  You can change your email address for this repo with the following command:
   632  </p>
   633  
   634  <pre>
   635  $ git config user.email email@address.com
   636  </pre>
   637  
   638  <p>
   639  Then change the previous commit to use this alternative email address.
   640  You can do that with:
   641  </p>
   642  
   643  <pre>
   644  $ git commit --amend --author="Author Name &lt;email@address.com&gt;"
   645  </pre>
   646  
   647  <p>
   648  Finally try to resend with:
   649  </p>
   650  
   651  <pre>
   652  $ git mail
   653  </pre>
   654  
   655  <h3 id="cc">Specifying a reviewer / CCing others</h3>
   656  
   657  <p>
   658  Unless explicitly told otherwise, such as in the discussion leading
   659  up to sending in the change, it's better not to specify a reviewer.
   660  All changes are automatically CC'ed to the
   661  <a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a>
   662  mailing list. If this is your first ever change, there may be a moderation
   663  delay before it appears on the mailing list, to prevent spam.
   664  </p>
   665  
   666  <p>
   667  You can specify a reviewer or CC interested parties
   668  using the <code>-r</code> or <code>-cc</code> options.
   669  Both accept a comma-separated list of email addresses:
   670  </p>
   671  
   672  <pre>
   673  $ git mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com
   674  </pre>
   675  
   676  <h2 id="review">Going through the review process</h2>
   677  
   678  <p>
   679  Running <code>git</code> <code>mail</code> will send an email to you and the
   680  reviewers asking them to visit the issue's URL and make comments on the change.
   681  When done, the reviewer adds comments through the Gerrit user interface
   682  and clicks "Reply" to send comments back.
   683  You will receive a mail notification when this happens.
   684  You may reply through the web interface or
   685  <a href="https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email">via email</a>.
   686  </p>
   687  
   688  <h3 id="revise">Revise and resend</h3>
   689  
   690  <p>
   691  The Go contribution workflow is optimized for iterative revisions based on
   692  feedback.
   693  It is rare that an initial contribution will be ready to be applied as is.
   694  As you revise your contribution and resend Gerrit will retain a history of
   695  all the changes and comments made in the single URL.
   696  </p>
   697  
   698  <p>
   699  You may respond to review comments through the web interface or
   700  <a href="https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email">via email</a>.
   701  </p>
   702  
   703  <p>
   704  When you have revised the code and are ready for another round of review,
   705  stage those changes and use <code>git</code> <code>change</code> to update the
   706  commit.
   707  To send the updated change for another round of review,
   708  run <code>git</code> <code>mail</code> again.
   709  </p>
   710  
   711  <p>
   712  The reviewer can comment on the new copy, and the process repeats.
   713  The reviewer approves the change by giving it a positive score
   714  (+1 or +2) and replying <code>LGTM</code>: looks good to me.
   715  </p>
   716  
   717  <p>
   718  You can see a list of your pending changes by running <code>git</code>
   719  <code>pending</code>, and switch between change branches with <code>git</code>
   720  <code>change</code> <code><i>&lt;branch&gt;</i></code>.
   721  </p>
   722  
   723  <h3 id="sync">Synchronize your client</h3>
   724  
   725  <p>
   726  While you were working, others might have submitted changes to the repository.
   727  To update your local branch, run
   728  </p>
   729  
   730  <pre>
   731  $ git sync
   732  </pre>
   733  
   734  <p>
   735  (In git terms, <code>git</code> <code>sync</code> runs
   736  <code>git</code> <code>pull</code> <code>-r</code>.)
   737  </p>
   738  
   739  <h3 id="resolving_conflicts">Resolving Conflicts</h3>
   740  
   741  <p>
   742  If files you were editing have changed, Git does its best to merge the
   743  remote changes into your local changes.
   744  It may leave some files to merge by hand.
   745  </p>
   746  
   747  <p>
   748  For example, suppose you have edited <code>sin.go</code> but
   749  someone else has committed an independent change.
   750  When you run <code>git</code> <code>sync</code>,
   751  you will get the (scary-looking) output:
   752  
   753  <pre>
   754  $ git sync
   755  Failed to merge in the changes.
   756  Patch failed at 0023 math: improved Sin, Cos and Tan precision for very large arguments
   757  The copy of the patch that failed is found in:
   758     /home/you/repo/.git/rebase-apply/patch
   759  
   760  When you have resolved this problem, run "git rebase --continue".
   761  If you prefer to skip this patch, run "git rebase --skip" instead.
   762  To check out the original branch and stop rebasing, run "git rebase --abort".
   763  </pre>
   764  
   765  <p>
   766  If this happens, run
   767  </p>
   768  
   769  <pre>
   770  $ git status
   771  </pre>
   772  
   773  <p>
   774  to see which files failed to merge.
   775  The output will look something like this:
   776  </p>
   777  
   778  <pre>
   779  rebase in progress; onto a24c3eb
   780  You are currently rebasing branch 'mcgillicutty' on 'a24c3eb'.
   781    (fix conflicts and then run "git rebase --continue")
   782    (use "git rebase --skip" to skip this patch)
   783    (use "git rebase --abort" to check out the original branch)
   784  
   785  Unmerged paths:
   786    (use "git reset HEAD &lt;file&gt;..." to unstage)
   787    (use "git add &lt;file&gt;..." to mark resolution)
   788  
   789  	<i>both modified: sin.go</i>
   790  </pre>
   791  
   792  <p>
   793  The only important part in that transcript is the italicized "both modified"
   794  line: Git failed to merge your changes with the conflicting change.
   795  When this happens, Git leaves both sets of edits in the file,
   796  with conflicts marked by <code>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</code> and
   797  <code>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</code>.
   798  It is now your job to edit the file to combine them.
   799  Continuing the example, searching for those strings in <code>sin.go</code>
   800  might turn up:
   801  </p>
   802  
   803  <pre>
   804  	arg = scale(arg)
   805  &lt;&lt;&lt;&lt;&lt;&lt;&lt; HEAD
   806  	if arg &lt; 1e9 {
   807  =======
   808  	if arg &lt; 1e10 {
   809  &gt;&gt;&gt;&gt;&gt;&gt;&gt; mcgillicutty
   810  		largeReduce(arg)
   811  </pre>
   812  
   813  <p>
   814  Git doesn't show it, but suppose the original text that both edits
   815  started with was 1e8; you changed it to 1e10 and the other change to 1e9,
   816  so the correct answer might now be 1e10.
   817  First, edit the section to remove the markers and leave the correct code:
   818  </p>
   819  
   820  <pre>
   821  	arg = scale(arg)
   822  	if arg &lt; 1e10 {
   823  		largeReduce(arg)
   824  </pre>
   825  
   826  <p>
   827  Then tell Git that the conflict is resolved by running
   828  </p>
   829  
   830  <pre>
   831  $ git add sin.go
   832  </pre>
   833  
   834  <p>
   835  If you had been editing the file, say for debugging, but do not
   836  care to preserve your changes, you can run
   837  <code>git</code> <code>reset</code> <code>HEAD</code> <code>sin.go</code>
   838  to abandon your changes.
   839  Then run <code>git</code> <code>rebase</code> <code>--continue</code> to
   840  restore the change commit.
   841  </p>
   842  
   843  <h3 id="download">Reviewing code by others</h3>
   844  
   845  <p>
   846  As part of the review process reviewers can propose changes directly (in the
   847  GitHub workflow this would be someone else attaching commits to a pull request).
   848  
   849  You can import these changes proposed by someone else into your local Git repository.
   850  On the Gerrit review page, click the "Download ▼" link in the upper right
   851  corner, copy the "Checkout" command and run it from your local Git repo. It
   852  should look something like this:
   853  </p>
   854  
   855  <pre>
   856  $ git fetch https://go.googlesource.com/review refs/changes/21/1221/1 &amp;&amp; git checkout FETCH_HEAD
   857  </pre>
   858  
   859  <p>
   860  To revert, change back to the branch you were working in.
   861  </p>
   862  
   863  <h2 id="submit">Apply the change to the master branch</h2>
   864  
   865  <p>
   866  After the code has been <code>LGTM</code>'ed, an approver may
   867  apply it to the master branch using the Gerrit UI.
   868  There is a "Submit" button on the web page for the change
   869  that appears once the change is approved (marked +2).
   870  </p>
   871  
   872  <p>
   873  This checks the change into the repository.
   874  The change description will include a link to the code review,
   875  and the code review will be updated with a link to the change
   876  in the repository.
   877  Since the method used to integrate the changes is "Cherry Pick",
   878  the commit hashes in the repository will be changed by
   879  the "Submit" operation.
   880  </p>
   881  
   882  <h2 id="more">More information</h2>
   883  
   884  <p>
   885  In addition to the information here, the Go community maintains a <a
   886  href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page.
   887  Feel free to contribute to this page as you learn the review process.
   888  </p>