# Contributing to Terraform - Google Provider

For a set of general guidelines, see the [CONTRIBUTING.md](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md) page in the main Terraform repository.

The following are certain Google Provider-specific things to be aware of when contributing.

## Go

See the root [README](../README.md) for information on which version of Go you need to use the provider. Generally, this will
be the latest stable release of Go.

We aim to make the Google Provider a good steward of Go practices. See https://github.com/golang/go/wiki/CodeReviewComments for common Go mistakes that you should attempt to avoid.

## Autogenerated Resources

We maintain 2 different versions of the Google Terraform provider; the [`google` provider](https://github.com/terraform-providers/terraform-provider-google) and the [`google-beta` provider](https://github.com/terraform-providers/terraform-provider-google-beta). The `google` provider supports GA ([general availability](https://cloud.google.com/terms/launch-stages)) features, and `google-beta` supports Beta features.

We are using code generation tool called [Magic Modules](https://github.com/googleCloudPlatform/magic-modules/) that uses a shared code base to generate both providers. Some Terraform resources are fully generated, whereas some resources are hand written and located in [the third_party/terraform/ folder in magic modules](https://github.com/GoogleCloudPlatform/magic-modules/tree/master/third_party/terraform/resources). Generated resources will have a prominent header at the top of the file identifying them. Hand written resources have a .go or .go.erb extension but will eventually be migrated into the code generation tool with the goal of having all resources fully generated.

For more details on Magic Modules please visit [the readme](https://github.com/GoogleCloudPlatform/magic-modules). For feature requests or bugs regarding those resources, please continue to file issues in the [terraform-provider-google issue tracker](https://github.com/terraform-providers/terraform-provider-google/issues). PRs changing those resources will not be accepted.

## Beta vs GA providers

Fields that are only available in beta versions of the Google Cloud Platform API will need to be added only to the `google-beta` provider and excluded from the `google` provider. When adding beta features or resources you will need to use templating to exclude them from generating into the ga version. Look for `*.erb` files in [resources](https://github.com/GoogleCloudPlatform/magic-modules/tree/master/third_party/terraform/resources) for examples.

## Vendoring Libraries

When adding support for just-released GCP features, you'll often need to vendor a new version of the Google API client.
The Google provider uses Go Modules; use the commands listed below and the new dependencies will be included in your PR.

```bash
GO111MODULES=on go get {{dependency}}
GO111MODULES=on go mod tidy
GO111MODULES=on go mod vendor
```

If you're developing against Magic Modules, vendoring changes needs to be done against each of the providers Magic Modules builds. At time of writing, that's this provider (`google`) and [`google-beta`](https://github.com/terraform-providers/terraform-provider-google-beta).

## Tests

### Running Tests

Configuring tests is similar to configuring the provider; see the [Provider Configuration Reference](https://www.terraform.io/docs/providers/google/provider_reference.html#configuration-reference) for more details. The following environment variables must be set in order to run tests:

```
GOOGLE_PROJECT
GOOGLE_CREDENTIALS
GOOGLE_REGION
GOOGLE_ZONE
```

To ensure that your tests are performed in a region and zone with wide support for GCP feature, `GOOGLE_REGION` should be set to `us-central1` and `GOOGLE_ZONE` to `us-central1-a`.

For certain tests, primarily those involving project creation, the following variables may also need to be set. Most tests do
not require their being set:

```
GOOGLE_ORG
GOOGLE_BILLING_ACCOUNT
```

To run a specific test, use `TESTARGS`, such as in:

```
make testacc TEST=./google TESTARGS='-run=TestAccContainerNodePool_basic'
```

The `TESTARGS` variable is regexp-like, so multiple tests can be run in parallel by specifying a common substring of those tests (for example, `TestAccContainerNodePool` to run all node pool tests).

To run all tests, you can omit the `TESTARGS` argument - but please keep in mind that that is quite a few tests and will take quite a long time and create some fairly expensive resources.  It usually is not advisable to run all tests.

### Writing Tests

Tests should confirm that a resource can be created, and that the resulting Terraform state has the correct values, as well as the created GCP resource.

Tests should confirm that the resource works in a variety of scenarios, and not just that it can be created in a basic fashion.

Resources that support update should have tests for update.

Resources that are importable should have a test that confirms that every field is importable. This should be part of an existing test (in the regular resource_test.go file) as an extra TestStep with the following format:
```
resource.TestStep{
	ResourceName:      "google_compute_backend_service.foobar",
	ImportState:       true,
	ImportStateVerify: true,
},
```

## Running a local copy of the provider
If you are building Terraform from source with a Google provider built from source, Terraform will automatically use the
local `terraform-provider-google` and `terraform-provider-google-beta` plugins in `$GOPATH/bin`.

In order to use a release copy of Terrafom with a local provider, you can use the [provider discovery directory](https://www.terraform.io/docs/extend/how-terraform-works.html#discovery)
at `~/.terraform.d/plugins`. When a copy of the Google provider is present in the discovery directory, `terraform init` will
use that copy instead of downloading a release version. If you've already used a release version of a provider in a given directory by running `terraform init`, Terraform will not use the locally built copy; remove the release version from the `./.terraform/` to start using your locally build copy.

To use a single locally built version, such as one built by a CI or build server, you can copy a `google` or `google-beta`
binary into the discovery directory. If you're testing a local provider in active development and want the new binary each
time you run `make build`, you can symlink the built binary into the directory:

```bash
ln -s $GOPATH/bin/terraform-provider-google ~/.terraform.d/plugins/terraform-provider-google
ln -s $GOPATH/bin/terraform-provider-google-beta ~/.terraform.d/plugins/terraform-provider-google-beta
```

# Maintainer-specific information

## Reviewing / Merging Code

When reviewing/merging code, roughly follow the guidelines set in the
[Maintainer's Etiquette](https://github.com/hashicorp/terraform/blob/master/docs/maintainer-etiquette.md)
guide. One caveat is that they're fairly old and apply primarily to HashiCorp employees, but the general guidance about merging / changelogs is still relevant.