Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[documentation]: update contributing doc #1282

Merged
merged 1 commit into from
Nov 29, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 103 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
----------------------

Expand Down