internal: overhaul CONTRIBUTING.md
- Add a few missing instructions, e.g. enabling APIs, adding API keys, etc
- Clarify several instructions
- Disambiguate between firestore and general project
- Subdivide the Setup steps
- Use backticks instead of bold for env vars
- Align text to standard 120 char
Change-Id: Ie369ae96f9d5dc0f33db5a4e9dadc7a95880f57f
Reviewed-on: https://code-review.googlesource.com/c/34491
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Eno Compton <enocom@google.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4e70c5d..af46c13 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,121 +1,177 @@
# Contributing
1. Sign one of the contributor license agreements below.
-1. `go get golang.org/x/review/git-codereview` to install the code reviewing tool.
+1. `go get golang.org/x/review/git-codereview` to install the code reviewing
+tool.
1. You will need to ensure that your `GOBIN` directory (by default
- `$GOPATH/bin`) is in your `PATH` so that git can find the command.
+ `$GOPATH/bin`) is in your `PATH` so that git can find the command.
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.
+ such that `git codereview change` becomes `git change`. See the
+ [godoc](https://godoc.org/golang.org/x/review/git-codereview) for details.
1. 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.
+ that all error messages will assume that you have set up these aliases.
1. Get the cloud package by running `go get -d cloud.google.com/go`.
- 1. If you have already checked out the source, make sure that the remote git
- origin is https://code.googlesource.com/gocloud:
+ 1. If you have already checked out the source, make sure that the remote
+ git origin is https://code.googlesource.com/gocloud:
- git remote set-url origin https://code.googlesource.com/gocloud
+ ```
+ git remote set-url origin https://code.googlesource.com/gocloud
+ ```
+
1. Make sure your auth is configured correctly by visiting
- https://code.googlesource.com, clicking "Generate Password", and following
- the directions.
+https://code.googlesource.com, clicking "Generate Password", and following the
+directions.
1. Make changes and create a change by running `git codereview change <name>`,
provide a commit message, and use `git codereview mail` to create a Gerrit CL.
-1. Keep amending to the change with `git codereview change` and mail as your receive
-feedback. Each new mailed amendment will create a new patch set for your change in Gerrit.
+1. Keep amending to the change with `git codereview change` and mail as your
+receive feedback. Each new mailed amendment will create a new patch set for
+your change in Gerrit.
## Integration Tests
-In addition to the unit tests, you may run the integration test suite.
+In addition to the unit tests, you may run the integration test suite. These
+directions describe setting up your environment to run integration tests for
+_all_ packages: note that many of these instructions may be redundant if you
+intend only to run integration tests on a single package.
-To run the integrations tests, creating and configuration of a project in the
-Google Developers Console is required.
+#### GCP Setup
-After creating a project, you must [create a service account](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount).
-Ensure the project-level **Owner**
-[IAM role](console.cloud.google.com/iam-admin/iam/project) role is added to the
-service account. Alternatively, the account can be granted all of the following roles:
-- **Editor**
-- **Logs Configuration Writer**
-- **PubSub Admin**
+To run the integrations tests, creation and configuration of two projects in
+the Google Developers Console is required: one specifically for Firestore
+integration tests, and another for all other integration tests. We'll refer to
+these projects as "general project" and "Firestore project".
-Once you create a project, set the following environment variables to be able to
-run the against the actual APIs.
+After creating each project, you must [create a service account](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount)
+for each project. Ensure the project-level **Owner**
+[IAM role](console.cloud.google.com/iam-admin/iam/project) role is added to
+each service account. During the creation of the service account, you should
+download the JSON credential file for use later.
-- **GCLOUD_TESTS_GOLANG_PROJECT_ID**: Developers Console project's ID (e.g. bamboo-shift-455)
-- **GCLOUD_TESTS_GOLANG_KEY**: The path to the JSON key file.
+Next, ensure the following APIs are enabled in the general project:
-Some packages require additional environment variables to be set:
+- BigQuery API
+- BigQuery Data Transfer API
+- Cloud Dataproc API
+- Cloud Dataproc Control API Private
+- Cloud Datastore API
+- Cloud Firestore API
+- Cloud Key Management Service (KMS) API
+- Cloud Natural Language API
+- Cloud OS Login API
+- Cloud Pub/Sub API
+- Cloud Resource Manager API
+- Cloud Spanner API
+- Cloud Speech API
+- Cloud Translation API
+- Cloud Video Intelligence API
+- Cloud Vision API
+- Compute Engine API
+- Compute Engine Instance Group Manager API
+- Container Registry API
+- Firebase Rules API
+- Google Cloud APIs
+- Google Cloud Deployment Manager V2 API
+- Google Cloud SQL
+- Google Cloud Storage
+- Google Cloud Storage JSON API
+- Google Compute Engine Instance Group Updater API
+- Google Compute Engine Instance Groups API
+- Kubernetes Engine API
+- Stackdriver Error Reporting API
-- firestore
- - **GCLOUD_TESTS_GOLANG_FIRESTORE_PROJECT_ID**: project ID for Firestore.
- - **GCLOUD_TESTS_GOLANG_FIRESTORE_KEY**: The path to the JSON key file.
-- storage
- - **GCLOUD_TESTS_GOLANG_KEYRING**: The full name of the keyring for the tests, in the
- form "projects/P/locations/L/keyRings/R".
-- translate
- - **GCLOUD_TESTS_API_KEY**: API key for using the Translate API.
-- profiler
- - **GCLOUD_TESTS_GOLANG_ZONE**: Compute Engine zone.
+Next, create a Datastore database in the general project, and a Firestore
+database in the Firestore project.
-Some packages can record the RPCs during integration tests to a file for
-subsequent replay. To record, pass the `-record` flag to `go test`. The
-recording will be saved to the _package_`.replay` file. To replay integration
-tests from a saved recording, the replay file must be present, the `-short` flag
-must be passed to `go test`, and the **GCLOUD_TESTS_GOLANG_ENABLE_REPLAY**
-environment variable must have a non-empty value.
+Finally, in the general project, create an API key for the translate API:
-Install the [gcloud command-line tool][gcloudcli] to your machine and use it
-to create some resources used in integration tests.
+- Go to GCP Developer Console.
+- Navigate to APIs & Services > Credentials.
+- Click Create Credentials > API Key.
+- Save this key for use in `GCLOUD_TESTS_API_KEY` as described below.
+
+#### Local Setup
+
+Once the two projects are created and configured, set the following environment
+variables:
+
+- `GCLOUD_TESTS_GOLANG_PROJECT_ID`: Developers Console project's ID (e.g.
+bamboo-shift-455) for the general project.
+- `GCLOUD_TESTS_GOLANG_KEY`: The path to the JSON key file of the general
+project's service account.
+- `GCLOUD_TESTS_GOLANG_FIRESTORE_PROJECT_ID`: Developers Console project's ID
+(e.g. doorway-cliff-677) for the Firestore project.
+- `GCLOUD_TESTS_GOLANG_FIRESTORE_KEY`: The path to the JSON key file of the
+Firestore project's service account.
+- `GCLOUD_TESTS_GOLANG_KEYRING`: The full name of the keyring for the tests,
+in the form
+"projects/P/locations/L/keyRings/R". The creation of this is described below.
+- `GCLOUD_TESTS_API_KEY`: API key for using the Translate API.
+- `GCLOUD_TESTS_GOLANG_ZONE`: Compute Engine zone.
+
+Install the [gcloud command-line tool][gcloudcli] to your machine and use it to
+create some resources used in integration tests.
From the project's root directory:
``` sh
-# Set the default project in your env.
+# Sets the default project in your env.
$ gcloud config set project $GCLOUD_TESTS_GOLANG_PROJECT_ID
-# Authenticate the gcloud tool with your account.
+# Authenticates the gcloud tool with your account.
$ gcloud auth login
# Create the indexes used in the datastore integration tests.
$ gcloud datastore create-indexes datastore/testdata/index.yaml
-# Create a Google Cloud storage bucket with the same name as your test project,
+# Creates a Google Cloud storage bucket with the same name as your test project,
# and with the Stackdriver Logging service account as owner, for the sink
# integration tests in logging.
$ gsutil mb gs://$GCLOUD_TESTS_GOLANG_PROJECT_ID
$ gsutil acl ch -g cloud-logs@google.com:O gs://$GCLOUD_TESTS_GOLANG_PROJECT_ID
-# Create a PubSub topic for integration tests of storage notifications.
+# Creates a PubSub topic for integration tests of storage notifications.
$ gcloud beta pubsub topics create go-storage-notification-test
# Next, go to the Pub/Sub dashboard in GCP console. Authorize the user
-# "service-<numberic project id>@gs-project-accounts.iam.gserviceaccount.com" as a publisher to that topic.
+# "service-<numberic project id>@gs-project-accounts.iam.gserviceaccount.com"
+# as a publisher to that topic.
-# Create a Spanner instance for the spanner integration tests.
+# Creates a Spanner instance for the spanner integration tests.
$ gcloud beta spanner instances create go-integration-test --config regional-us-central1 --nodes 1 --description 'Instance for go client test'
-# NOTE: Spanner instances are priced by the node-hour, so you may want to delete
-# the instance after testing with 'gcloud beta spanner instances delete'.
+# NOTE: Spanner instances are priced by the node-hour, so you may want to
+# delete the instance after testing with 'gcloud beta spanner instances delete'.
-# For Storage integration tests:
-# Enable KMS for your project in the Cloud Console.
$ export MY_KEYRING=some-keyring-name
$ export MY_LOCATION=global
-# Create a KMS keyring, in the same location as the default location for your project's buckets.
+# Creates a KMS keyring, in the same location as the default location for your
+# project's buckets.
$ gcloud kms keyrings create $MY_KEYRING --location $MY_LOCATION
-# Create two keys in the keyring, named key1 and key2.
+# Creates two keys in the keyring, named key1 and key2.
$ gcloud kms keys create key1 --keyring $MY_KEYRING --location $MY_LOCATION --purpose encryption
$ gcloud kms keys create key2 --keyring $MY_KEYRING --location $MY_LOCATION --purpose encryption
-# As mentioned above, set the GCLOUD_TESTS_GOLANG_KEYRING environment variable.
+# Sets the GCLOUD_TESTS_GOLANG_KEYRING environment variable.
$ export GCLOUD_TESTS_GOLANG_KEYRING=projects/$GCLOUD_TESTS_GOLANG_PROJECT_ID/locations/$MY_LOCATION/keyRings/$MY_KEYRING
-# Authorize Google Cloud Storage to encrypt and decrypt using key1.
+# Authorizes Google Cloud Storage to encrypt and decrypt using key1.
gsutil kms authorize -p $GCLOUD_TESTS_GOLANG_PROJECT_ID -k $GCLOUD_TESTS_GOLANG_KEYRING/cryptoKeys/key1
```
-Once you've done the necessary setup, you can run the integration tests by running:
+#### Running
+
+Once you've done the necessary setup, you can run the integration tests by
+running:
``` sh
$ go test -v cloud.google.com/go/...
```
+#### Replay
+
+Some packages can record the RPCs during integration tests to a file for
+subsequent replay. To record, pass the `-record` flag to `go test`. The
+recording will be saved to the _package_`.replay` file. To replay integration
+tests from a saved recording, the replay file must be present, the `-short`
+flag must be passed to `go test`, and the `GCLOUD_TESTS_GOLANG_ENABLE_REPLAY`
+environment variable must have a non-empty value.
+
## Contributor License Agreements
Before we can accept your pull requests you'll need to sign a Contributor
