diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 16539b2de..dbf4ceece 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,32 +12,39 @@ $ $GOPATH/bin/terraform-provider-digitalocean ... ``` +### Running unit tests In order to test the provider, you can simply run `make test`. ```sh $ make test ``` -In order to run the full suite of acceptance tests, run `make testacc`. +### Running Acceptance Tests -*Note:* Acceptance tests create real resources, and often cost money to run. - -```sh -$ make testacc -``` +Please be aware that **running ALL acceptance tests will take a significant amount of time and could be expensive**, as they interact with your **real DigitalOcean account**. For this reason, it is highly recommended to run only one acceptance test at a time to minimize both time and cost. +- It is preferable to run one acceptance test at a time. In order to run a specific acceptance test, use the `TESTARGS` environment variable. For example, the following command will run `TestAccDigitalOceanDomain_Basic` acceptance test only: ```sh $ make testacc TESTARGS='-run=TestAccDigitalOceanDomain_Basic' ``` -All acceptance tests for a specific package can be run by setting the `PKG_NAME` environment variable. For example: +- All acceptance tests for a specific package can be run by setting the `PKG_NAME` environment variable. For example: ```sh $ make testacc PKG_NAME=digitalocean/account ``` +- In order to run the full suite of acceptance tests, run `make testacc`. + +**Note:** Acceptance tests create real resources, and often cost money to run. + +```sh +$ make testacc +``` + +### To check changes made locally In order to check changes you made locally to the provider, you can use the binary you just compiled by adding the following to your `~/.terraformrc` file. This is valid for Terraform 0.14+. Please see [Terraform's documentation](https://www.terraform.io/docs/cli/config/config-file.html#development-overrides-for-provider-developers) @@ -63,6 +70,95 @@ provider_installation { For information about writing acceptance tests, see the main Terraform [contributing guide](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md#writing-acceptance-tests). +Testing Your Changes Locally +---------------------------- + +### 1. Rebuilding the Provider +To apply your changes, you need to rebuild the provider: + +Run the following command to rebuild the provider from the root directory of the project: + +```console +make build +``` + +### 2. Creating a Sample Terraform Configuration +2.1 From the root of the project, create a directory for your Terraform configuration: + +```console +mkdir -p examples/my-tf +``` + +2.2 Create a new Terraform configuration file: + +``` console +touch examples/my-tf/main.tf +``` + +2.3 Populate the main.tf file with the following example configuration. +* [Available versions for the DigitalOcean Terraform provider](https://registry.terraform.io/providers/digitalocean/digitalocean/latest) +* Make sure to update the token value with your own [DigitalOcean token](https://docs.digitalocean.com/reference/api/create-personal-access-token). + +```console +terraform { + required_providers { + digitalocean = { + source = "digitalocean/digitalocean" + version = ">= 2.44.1" + } + } +} + +provider "digitalocean" { + token = "dop_v1_12345d7ce104413a59023656565" +} + +resource "digitalocean_droplet" "foobar-my-tf" { + image = "ubuntu-22-04-x64" + name = "tf-acc-test-my-tf" + region = "nyc3" + size = "s-1vcpu-1gb" +} +``` +2.4 Before using the Terraform configuration, you need to initialize your working directory. +```console +cd examples/my-tf +terraform init +``` + +### 3. Running Terraform Commands +3.1 Navigate to the working directory: + +```console +cd examples/my-tf +``` + +3.2 To see the changes that will be applied run: + +```console +terraform plan +``` + +3.3 To apply the changes run: + +```console +terraform apply +``` +This will interact with your DigitalOcean account, using the token you provided in the `main.tf` configuration file. +Once you've finished testing, it's a good practice to clean up any resources you created to avoid incurring charges. + +### 4. Debugging and Logging +You can add logs to your code with `log.Printf()`. Remember to run `make build` to apply changes. + +If you'd like to see more detailed logs for debugging, you can set the `TF_LOG` environment variable to `DEBUG` or `TRACE`. + +``` console +export TF_LOG=DEBUG +export TF_LOG=TRACE +``` + +After setting the log level, you can run `terraform plan` or `terraform apply` again to see more detailed output. + Releasing the Provider ----------------------