diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..8fff4ac8 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# 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 + +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. + +## Tests + +### Running Tests + +The following environment variables must be set in order to run tests: +``` +GOOGLE_PROJECT +GOOGLE_CREDENTIALS or GOOGLE_USE_DEFAULT_CREDENTIALS +``` +For certain tests, the following variables may also need to be set: +``` +GOOGLE_REGION +GOOGLE_ORG +GOOGLE_BILLING_ACCOUNT +``` + +To run a specific test, use a command such as: +``` +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). + +### 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, +}, +``` + +## Autogenerated Resources + +Some resources in the Google provider are autogenerated using the [Magic Modules](https://github.com/GoogleCloudPlatform/magic-modules) framework, and have a large disclaimer as a comment at the top of their files to say so. For feature requests or bugs regarding those resources, please continue to file [issues](https://github.com/terraform-providers/terraform-provider-google/issues) here. PRs changing those resources will not be accepted. \ No newline at end of file