docs: update CONTRIBUTING.md
Updates the CONTRIBUTING.md to match relevant parts of google-cloud-go.
Change-Id: Id96d7767b2a57ef7948adb37877a440449902908
Reviewed-on: https://code-review.googlesource.com/c/google-api-go-client/+/46973
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Cody Oss <codyoss@google.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4f90ff9..bc56b50 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,483 +1,159 @@
-# Contributing to the Google API Go Client
+# Contributing
-## Master git repo
+1. [Install Go](https://golang.org/dl/).
+ 1. Ensure that your `GOBIN` directory (by default `$(go env GOPATH)/bin`)
+ is in your `PATH`.
+ 1. Check it's working by running `go version`.
+ * If it doesn't work, check the install location, usually
+ `/usr/local/go`, is on your `PATH`.
-Our master git repo is https://code.googlesource.com/google-api-go-client
+1. Sign one of the
+[contributor license agreements](#contributor-license-agreements) below.
-## Pull Requests
+1. Run `GO111MODULE=off go get golang.org/x/review/git-codereview` to install
+the code reviewing tool.
-We do **NOT** use Github pull requests. We use Gerrit instead
-with the same workflow as Go. See below.
+ 1. Ensure it's working by running `git codereview` (check your `PATH` if
+ not).
-## The source tree
+ 1. If you would like, you may want to set up aliases for `git-codereview`,
+ such that `git codereview change` becomes `git change`. See the
+ [godoc](https://godoc.org/golang.org/x/review/git-codereview) for details.
-Most of this project is auto-generated.
+ * Should you run into issues with the `git-codereview` tool, please note
+ that all error messages will assume that you have set up these aliases.
-The notable directories which are not auto-generated:
+1. Change to a directory of your choosing and clone the repo.b
-```
- google-api-go-generator/ -- the generator itself
- googleapi/ -- shared common code, used by auto-generated code
- examples/ -- sample code
-```
+ ```
+ cd ~/code
+ git clone https://code.googlesource.com/gocloud
+ ```
-# Contribution Guidelines
+ * If you have already checked out the source, make sure that the remote
+ `git` `origin` is https://code.googlesource.com/gocloud:
-## Introduction
+ ```
+ git remote -v
+ # ...
+ git remote set-url origin https://code.googlesource.com/gocloud
+ ```
-This document explains how to contribute changes to the google-api-go-client project.
+ * The project uses [Go Modules](https://blog.golang.org/using-go-modules)
+ for dependency management See
+ [`gopls`](https://github.com/golang/go/wiki/gopls) for making your editor
+ work with modules.
-## Testing redux
+1. Change to the project directory:
-You've written and tested your code, but
-before sending code out for review, run all the tests for the whole
-tree to make sure the changes don't break other packages or programs:
+ ```
+ cd ~/code/gocloud
+ ```
-```
-$ make cached
-$ go test ./...
-...
-ok google.golang.org/api/google-api-go-generator 0.226s
-ok google.golang.org/api/googleapi 0.015s
-...
-```
+1. Make sure your `git` auth is configured correctly by visiting
+https://code.googlesource.com, clicking "Generate Password" at the top-right,
+and following the directions. Otherwise, `git codereview mail` in the next step
+will fail.
-Ideally, you will add unit tests to one of the above directories to
-demonstrate the changes you are making and include the tests with your
-code review.
+1. Now you are ready to make changes. Don't create a new branch or make commits in the traditional
+way. Use the following`git codereview` commands to create a commit and create a Gerrit CL:
-## Code review
+ ```
+ git codereview change <branch-name> # Use this instead of git checkout -b <branch-name>
+ # Make changes.
+ git add ...
+ git codereview change # Use this instead of git commit
+ git codereview mail # If this fails, the error message will contain instructions to fix it.
+ ```
-Changes to google-api-go-client must be reviewed before they are submitted,
-no matter who makes the change.
-A custom git command called `git-codereview`,
-discussed below, helps manage the code review process through a Google-hosted
-[instance](https://code-review.googlesource.com/) of the code review
-system called [Gerrit](https://code.google.com/p/gerrit/).
+ * This will create a new `git` branch for you to develop on. Once your
+ change is merged, you can delete this branch.
-### Set up authentication for code review
+1. As you make changes for code review, ammend the commit and re-mail the
+change:
-The Git code hosting server and Gerrit code review server both use a Google
-Account to authenticate. You therefore need a Google Account to proceed.
-(If you can use the account to
-[sign in at google.com](https://www.google.com/accounts/Login),
-you can use it to sign in to the code review server.)
-The email address you use with the code review system
-needs to be added to the [`CONTRIBUTORS`](/CONTRIBUTORS) file
-with your first code review.
-You can [create a Google Account](https://www.google.com/accounts/NewAccount)
-associated with any address where you receive email.
+ ```
+ # Make more changes.
+ git add ...
+ git codereview change
+ git codereview mail
+ ```
-Visit the site [code.googlesource.com](https://code.googlesource.com)
-and log in using your Google Account.
-Click on the "Generate Password" link that appears at the top of the page.
+ * **Warning**: do not change the `Change-Id` at the bottom of the commit
+ message - it's how Gerrit knows which change this is (or if it's new).
-Click the radio button that says "Only `code.googlesource.com`"
-to use this authentication token only for the google-api-go-client project.
+ * When you fixes issues from code review, respond to each code review
+ message then click **Reply** at the top of the page.
-Further down the page is a box containing commands to install
-the authentication cookie in file called `.gitcookies` in your home
-directory.
-Copy the text for the commands into a Unix shell window to execute it.
-That will install the authentication token.
+ * Each new mailed amendment will create a new patch set for
+ your change in Gerrit. Patch sets can be compared and reviewed.
-(If you are on a Windows computer, you should instead follow the instructions
-in the yellow box to run the command.)
+ * **Note**: if your change includes a breaking change, our breaking change
+ detector will cause CI/CD to fail. If your breaking change is acceptable
+ in some way, add a `BREAKING_CHANGE_ACCEPTABLE=<reason>` line to the commit
+ message to cause the detector not to be run and to make it clear why that is
+ acceptable.
-### Register with Gerrit
+1. Finally, add reviewers to your CL when it's ready for review. Reviewers will
+not be added automatically. If you're not sure who to add for your code review,
+add deklerk@, tbp@, cbro@, and codyoss@.
-Now that you have a Google account and the authentication token,
-you need to register your account with Gerrit, the code review system.
-To do this, visit [golang.org/cl](https://golang.org/cl)
-and log in using the same Google Account you used above.
-That is all that is required.
+## Contributor License Agreements
-### Install the git-codereview command
+Before we can accept your pull requests you'll need to sign a Contributor
+License Agreement (CLA):
-Now install the `git-codereview` command by running,
+- **If you are an individual writing original source code** and **you own the
+intellectual property**, then you'll need to sign an [individual CLA][indvcla].
+- **If you work for a company that wants to allow you to contribute your
+work**, then you'll need to sign a [corporate CLA][corpcla].
-```
-go get -u golang.org/x/review/git-codereview
-```
+You can sign these electronically (just scroll to the bottom). After that,
+we'll be able to accept your pull requests.
-Make sure `git-codereview` is installed in your shell path, so that the
-`git` command can find it. Check that
+## Contributor Code of Conduct
-```
-$ git codereview help
-```
+As contributors and maintainers of this project,
+and in the interest of fostering an open and welcoming community,
+we pledge to respect all people who contribute through reporting issues,
+posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
-prints help text, not an error.
+We are committed to making participation in this project
+a harassment-free experience for everyone,
+regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
-Note to Git aficionados: The `git-codereview` command is not required to
-upload and manage Gerrit code reviews. For those who prefer plain Git, the text
-below gives the Git equivalent of each git-codereview command. If you do use plain
-Git, note that you still need the commit hooks that the git-codereview command
-configures; those hooks add a Gerrit `Change-Id` line to the commit
-message and check that all Go source files have been formatted with gofmt. Even
-if you intend to use plain Git for daily work, install the hooks in a new Git
-checkout by running `git-codereview hooks`.
+Examples of unacceptable behavior by participants include:
-### Set up git aliases
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information,
+such as physical or electronic
+addresses, without explicit permission
+* Other unethical or unprofessional conduct.
-The `git-codereview` command can be run directly from the shell
-by typing, for instance,
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct.
+By adopting this Code of Conduct,
+project maintainers commit themselves to fairly and consistently
+applying these principles to every aspect of managing this project.
+Project maintainers who do not follow or enforce the Code of Conduct
+may be permanently removed from the project team.
-```
-$ git codereview sync
-```
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
-but it is more convenient to set up aliases for `git-codereview`'s own
-subcommands, so that the above becomes,
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported by opening an issue
+or contacting one or more of the project maintainers.
-```
-$ git sync
-```
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0,
+available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
-The `git-codereview` subcommands have been chosen to be distinct from
-Git's own, so it's safe to do so.
-
-The aliases are optional, but in the rest of this document we will assume
-they are installed.
-To install them, copy this text into your Git configuration file
-(usually `.gitconfig` in your home directory):
-
-```
-[alias]
- change = codereview change
- gofmt = codereview gofmt
- mail = codereview mail
- pending = codereview pending
- submit = codereview submit
- sync = codereview sync
-```
-
-### Understanding the git-codereview command
-
-After installing the `git-codereview` command, you can run
-
-```
-$ git codereview help
-```
-
-to learn more about its commands.
-You can also read the [command documentation](https://godoc.org/golang.org/x/review/git-codereview).
-
-### Switch to the master branch
-
-New changes should
-only be made based on the master branch.
-Before making a change, make sure you start on the master branch:
-
-```
-$ git checkout master
-$ git sync
-````
-
-(In Git terms, `git sync` runs
-`git pull -r`.)
-
-### Make a change
-
-The entire checked-out tree is writable.
-Once you have edited files, you must tell Git that they have been modified.
-You must also tell Git about any files that are added, removed, or renamed files.
-These operations are done with the usual Git commands,
-`git add`,
-`git rm`,
-and
-`git mv`.
-
-If you wish to checkpoint your work, or are ready to send the code out for review, run
-
-```
-$ git change <branch>
-```
-
-from any directory in your google-api-go-client repository to commit the changes so far.
-The name `<branch>` is an arbitrary one you choose to identify the
-local branch containing your changes.
-
-(In Git terms, `git change <branch>`
-runs `git checkout -b branch`,
-then `git branch --set-upstream-to origin/master`,
-then `git commit`.)
-
-Git will open a change description file in your editor.
-(It uses the editor named by the `$EDITOR` environment variable,
-`vi` by default.)
-The file will look like:
-
-```
-# Please enter the commit message for your changes. Lines starting
-# with '#' will be ignored, and an empty message aborts the commit.
-# On branch foo
-# Changes not staged for commit:
-# modified: editedfile.go
-#
-```
-
-At the beginning of this file is a blank line; replace it
-with a thorough description of your change.
-The first line of the change description is conventionally a one-line
-summary of the change, prefixed by `google-api-go-client:`,
-and is used as the subject for code review mail.
-The rest of the
-description elaborates and should provide context for the
-change and explain what it does.
-If there is a helpful reference, mention it here.
-
-After editing, the template might now read:
-
-```
-math: improved 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 http://wikipedia.org/wiki/McGillicutty_Algorithm
-
-Fixes #54
-
-# Please enter the commit message for your changes. Lines starting
-# with '#' will be ignored, and an empty message aborts the commit.
-# On branch foo
-# Changes not staged for commit:
-# modified: editedfile.go
-#
-```
-
-The commented section of the file lists all the modified files in your client.
-It is best to keep unrelated changes in different change lists,
-so if you see a file listed that should not be included, abort
-the command and move that file to a different branch.
-
-The special notation "Fixes #54" associates the change with issue 54 in the
-[google-api-go-client issue tracker](https://github.com/google/google-api-go-client/issues/54).
-When this change is eventually submitted, the issue
-tracker will automatically mark the issue as fixed.
-(There are several such conventions, described in detail in the
-[GitHub Issue Tracker documentation](https://help.github.com/articles/closing-issues-via-commit-messages/).)
-
-Once you have finished writing the commit message,
-save the file and exit the editor.
-
-If you wish to do more editing, re-stage your changes using
-`git add`, and then run
-
-```
-$ git change
-```
-
-to update the change description and incorporate the staged changes. The
-change description contains a `Change-Id` line near the bottom,
-added by a Git commit hook during the initial
-`git change`.
-That line is used by Gerrit to match successive uploads of the same change.
-Do not edit or delete it.
-
-(In Git terms, `git change` with no branch name
-runs `git commit --amend`.)
-
-### Mail the change for review
-
-Once the change is ready, mail it out for review:
-
-```
-$ git mail
-```
-
-You can specify a reviewer or CC interested parties
-using the `-r` or `-cc` options.
-Both accept a comma-separated list of email addresses:
-
-```
-$ git mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com
-```
-
-Unless explicitly told otherwise, such as in the discussion leading
-up to sending in the change list, please specify
-`deklerk@google.com` and `cbro@google.com` as reviewers.
-
-(In Git terms, `git mail` pushes the local committed
-changes to Gerrit using `git push origin HEAD:refs/for/master`.)
-
-If your change relates to an open issue, please add a comment to the issue
-announcing your proposed fix, including a link to your CL.
-
-The code review server assigns your change an issue number and URL,
-which `git mail` will print, something like:
-
-```
-remote: New Changes:
-remote: https://code-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments
-```
-
-### Reviewing code
-
-Running `git mail` will send an email to you and the
-reviewers asking them to visit the issue's URL and make comments on the change.
-When done, the reviewer adds comments through the Gerrit user interface
-and clicks "Reply" to send comments back.
-You will receive a mail notification when this happens.
-You must reply through the web interface.
-
-### Revise and upload
-
-You must respond to review comments through the web interface.
-
-When you have revised the code and are ready for another round of review,
-stage those changes and use `git change` to update the
-commit.
-To send the update change list for another round of review,
-run `git mail` again.
-
-The reviewer can comment on the new copy, and the process repeats.
-The reviewer approves the change by giving it a positive score
-(+1 or +2) and replying `LGTM`: looks good to me.
-
-You can see a list of your pending changes by running
-`git pending`, and switch between change branches with
-`git change <branch>`.
-
-### Synchronize your client
-
-While you were working, others might have submitted changes to the repository.
-To update your local branch, run
-
-```
-$ git sync
-```
-
-(In git terms, `git sync` runs
-`git pull -r`.)
-
-If files you were editing have changed, Git does its best to merge the
-remote changes into your local changes.
-It may leave some files to merge by hand.
-
-For example, suppose you have edited `sin.go` but
-someone else has committed an independent change.
-When you run `git sync`,
-you will get the (scary-looking) output:
-
-```
-$ git sync
-Failed to merge in the changes.
-Patch failed at 0023 math: improved Sin, Cos and Tan precision for very large arguments
-The copy of the patch that failed is found in:
- /home/you/repo/.git/rebase-apply/patch
-
-When you have resolved this problem, run "git rebase --continue".
-If you prefer to skip this patch, run "git rebase --skip" instead.
-To check out the original branch and stop rebasing, run "git rebase --abort".
-```
-
-
-If this happens, run
-
-```
-$ git status
-```
-
-to see which files failed to merge.
-The output will look something like this:
-
-```
-rebase in progress; onto a24c3eb
-You are currently rebasing branch 'mcgillicutty' on 'a24c3eb'.
- (fix conflicts and then run "git rebase --continue")
- (use "git rebase --skip" to skip this patch)
- (use "git rebase --abort" to check out the original branch)
-
-Unmerged paths:
- (use "git reset HEAD <file>..." to unstage)
- (use "git add <file>..." to mark resolution)
-
- _both modified: sin.go_
-```
-
-
-The only important part in that transcript is the italicized "both modified"
-line: Git failed to merge your changes with the conflicting change.
-When this happens, Git leaves both sets of edits in the file,
-with conflicts marked by `<<<<<<<` and
-`>>>>>>>`.
-It is now your job to edit the file to combine them.
-Continuing the example, searching for those strings in `sin.go`
-might turn up:
-
-```
- arg = scale(arg)
-<<<<<<< HEAD
- if arg > 1e9 {
-=======
- if arg > 1e10 {
->>>>>>> mcgillicutty
- largeReduce(arg)
-```
-
-Git doesn't show it, but suppose the original text that both edits
-started with was 1e8; you changed it to 1e10 and the other change to 1e9,
-so the correct answer might now be 1e10. First, edit the section
-to remove the markers and leave the correct code:
-
-```
- arg = scale(arg)
- if arg > 1e10 {
- largeReduce(arg)
-```
-
-Then tell Git that the conflict is resolved by running
-
-```
-$ git add sin.go
-```
-
-If you had been editing the file, say for debugging, but do not
-care to preserve your changes, you can run
-`git reset HEAD sin.go`
-to abandon your changes.
-Then run `git rebase --continue` to
-restore the change commit.
-
-### Reviewing code by others
-
-You can import a change 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 should look something like this:
-
-```
-$ git fetch https://code.googlesource.com/review refs/changes/21/1221/1 && git checkout FETCH_HEAD
-```
-
-To revert, change back to the branch you were working in.
-
-### Submit the change after the review
-
-After the code has been `LGTM`'ed, an approver may
-submit it to the master branch using the Gerrit UI.
-There is a "Submit" button on the web page for the change
-that appears once the change is approved (marked +2).
-
-This checks the change into the repository.
-The change description will include a link to the code review,
-and the code review will be updated with a link to the change
-in the repository.
-Since the method used to integrate the changes is "Cherry Pick",
-the commit hashes in the repository will be changed by
-the submit operation.
-
-### More information
-
-In addition to the information here, the Go community maintains a [CodeReview](https://golang.org/wiki/CodeReview) wiki page.
-Feel free to contribute to this page as you learn the review process.
-
-## Contributors
-
-Files in the google-api-go-client repository don't list author names,
-both to avoid clutter and to avoid having to keep the lists up to date.
-Instead, please add your name to the [`CONTRIBUTORS`](/CONTRIBUTORS)
-file as your first code review, keeping the names in sorted order.
+[indvcla]: https://developers.google.com/open-source/cla/individual
+[corpcla]: https://developers.google.com/open-source/cla/corporate
