CONTRIBUTING.md

Contributing to Terraform - Salesforce 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 Salesforce 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:

SALESFORCE_CLIENT_ID
SALESFORCE_PRIVATE_KEY
SALESFORCE_API_VERSION
SALESFORCE_USERNAME

If running tests or using the provider against a "Sandbox Org" please be sure to set

SALESFORCE_LOGIN_URL="https://test.salesforce.com"

The tests and provider assume the profile of the specified SALESFORCE_USERNAME has "System Administrator" permissions.

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 Salesforce 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:      "salesforce_user.my-new-user",
	ImportState:       true,
	ImportStateVerify: true,
},

Instructing Terraform to use a local copy of the provider

Note that these instructions apply to 0.15+ however the provider was built using a new Terraform Framework that requires 1.0.3+.

Using released terraform binary with local provider binary

Setup:

mkdir -p ~/.terraform.d/plugins/registry.terraform.io/hashicorp/salesforce/5.0.0/darwin_amd64
ln -s $GOBIN/terraform-provider-salesforce ~/.terraform.d/plugins/registry.terraform.io/hashicorp/salesforce/5.0.0/darwin_amd64/terraform-provider-salesforce_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/salesforce"]
	}
}

Once this setup is complete, terraform will automatically use the binaries generated by the make build commands in the terraform-provider-salesforce 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.