terraform-provider-google/.github/CONTRIBUTING.md

Contributing to Terraform - Google Provider

For a set of general guidelines, see the 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 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 and the google-beta provider. The google provider supports GA (general availability) features, and google-beta supports Beta features.

We are using code generation tool called 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. 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. For feature requests or bugs regarding those resources, please continue to file issues in the terraform-provider-google issue tracker. 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 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.

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.

Tests

Running Tests

Configuring tests is similar to configuring the provider; see the Provider 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 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:

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 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.