Skip to content

Latest commit

 

History

History
111 lines (74 loc) · 5.27 KB

CONTRIBUTING.md

File metadata and controls

111 lines (74 loc) · 5.27 KB
Raw

Contributing to Terraform - Google Workspace Provider

For a set of general guidelines, see the CONTRIBUTING.md page in the main Terraform repository.

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

Go

See the test.yml file for which version of Go to use while developing the provider. You can manage it automatically using goenv.

We aim to make the Google Workspace 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

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:

GOOGLEWORKSPACE_CUSTOMER_ID
GOOGLEWORKSPACE_DOMAIN
GOOGLEWORKSPACE_IMPERSONATED_USER_EMAIL
GOOGLEWORKSPACE_IMPERSONATED_SERVICE_ACCOUNT
GOOGLEWORKSPACE_CREDENTIALS|GOOGLEWORKSPACE_CLOUD_KEYFILE_JSON|GOOGLEWORKSPACE_USE_DEFAULT_CREDENTIALS|GOOGLE_CREDENTIALS

Note that the credentials you provide must be granted wide permissions on the specified domain.

These tests provision real resources, and require permission in order to do so. Most developers on the team grant their impersonated user SuperAdmin role in their domain.

When running tests, specify which to run using TESTARGS, such as:

make testacc TESTARGS='-run=TestAccResourceUser_customSchemas'

The TESTARGS variable is regexp-like, so multiple tests can be run in parallel by specifying a common substring of those tests (for example, TestAccResourceUser to run all user 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 Google Workspace 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:      "googleworkspace_user.my-new-user",
	ImportState:       true,
	ImportStateVerify: true,
},

Sweepers

Running provider tests often can lead to dangling test resources caused by test failures. Terraform has a capability to run Sweepers which can go through and delete resources. In the Google Workspace provider, sweepers mainly:

  1. List every resource of a specific kind
  2. Iterate through the list and determine if a resource is sweepable
  3. If sweepable, delete the resource

Sweepers run by using the -sweep-run flag:

make sweep SWEEPARGS='<sweeper-name-here>'

or make sweep to run all sweepers.

Instructing Terraform to use a local copy of the provider

Note that these instructions apply to 0.15+.

Using released terraform binary with local provider binary

Setup:

mkdir -p ~/.terraform.d/plugins/registry.terraform.io/hashicorp/googleworkspace/5.0.0/darwin_amd64
ln -s $GOBIN/terraform-provider-googleworkspace ~/.terraform.d/plugins/registry.terraform.io/hashicorp/googleworkspace/5.0.0/darwin_amd64/terraform-provider-googleworkspace_v5.0.0

Edit the provider_installation block in your ~/.terraformrc file to:

plugin_cache_dir   = "~/.terraform.d/plugin-cache"

provider_installation {
	filesystem_mirror {
		path = "~/.terraform.d/plugin-cache"
		include = ["registry.terraform.io/hashicorp/googleworkspace"]
	}
}

Once this setup is complete, terraform will automatically use the binaries generated by the make build commands in the terraform-provider-googleworkspace repository instead of downloading the latest versions. To undo this, you can run:

rm -rf ~/.terraform.d/plugins/registry.terraform.io/hashicorp/

For more information, check out Hashicorp's documentation on the provider installation and using in-house providers.

If multiple versions are available in a plugin directory (for example after terraform providers mirror is used), Terraform will pick the most up-to-date provider version within version constraints. As such, we recommend using a version that is several major versions ahead for your local copy of the provider, such as 5.0.0.

Maintainer-specific information

Reviewing / Merging Code

When reviewing/merging code, roughly follow the guidelines set in the Maintainer's Etiquette guide.