From de8cb6100ad67e4e40a0fb3b227171f51c6c3f48 Mon Sep 17 00:00:00 2001 From: Chris Stephens Date: Mon, 12 Nov 2018 17:55:33 -0800 Subject: [PATCH] update contributing since beta split --- .github/CONTRIBUTING.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c941fafa..02408304 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -8,6 +8,18 @@ The following are certain Google Provider-specific things to be aware of when co 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 and @@ -72,7 +84,7 @@ resource.TestStep{ ``` ## 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 +If you are building Terraform from source with a Google provider built from source, Terraform will automatically use the local `terraform-provider-google` plugin 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) @@ -86,7 +98,3 @@ 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 ``` - -## 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.