Skip to content

Commit

Permalink
Update CONTRIBUTING
Browse files Browse the repository at this point in the history
  • Loading branch information
sergiught committed Feb 3, 2023
1 parent e7fbf7e commit 80cce72
Showing 1 changed file with 60 additions and 34 deletions.
94 changes: 60 additions & 34 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,32 @@
# Contributing

Before you begin, read through the Terraform documentation on
[Extending Terraform](https://www.terraform.io/docs/extend/index.html) and
[Writing Custom Providers](https://learn.hashicorp.com/collections/terraform/providers).

Finally,
the [HashiCorp Provider Design Principles](https://www.terraform.io/docs/extend/hashicorp-provider-design-principles.html)
explore the underlying principles for the design choices of this provider.
We appreciate feedback and contribution to this repo.
Before you submit a pull request, there are a couple requirements to satisfy.

## Prerequisites

- [Go 1.18+](https://go.dev/)
- [Terraform](https://developer.hashicorp.com/terraform/downloads)

## Reading Material

- [Extending Terraform](https://www.terraform.io/docs/extend/index.html) - design, develop, and test plugins that connect Terraform to external services.
- [Writing Custom Providers](https://learn.hashicorp.com/collections/terraform/providers) - tutorials on interacting with APIs using Terraform providers.
- [HashiCorp Provider Design Principles](https://www.terraform.io/docs/extend/hashicorp-provider-design-principles.html) - explore the underlying principles for the design choices of this provider.

## Getting started
## Getting Started

To work on the provider, you'll need [Go](http://www.golang.org) installed on your machine(version 1.18+ is *required*).
You'll also need to correctly set up a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin`
to your `$PATH`.
To work on the provider, you'll need [Go](https://go.dev/) installed on your machine(version 1.18+ is *required*).
You'll also need to set up a [`$GOPATH`](https://go.dev/doc/code.html#GOPATH), and add `$GOPATH/bin` to your `$PATH`.

To compile the provider, run `make install VERSION=X.X.X`. This will build the provider and install the provider binary
in the `${HOME}/.terraform.d/plugins` directory, so it can be used directly in terraform `required_providers` block.

```sh
```shell
make install VERSION=0.2.0
...
~/.terraform.d/plugins/registry.terraform.io/auth0/auth0/0.2.0/darwin_amd64/terraform-provider-auth0_v0.2.0
# On macOS, this will install the provider in:
# ~/.terraform.d/plugins/registry.terraform.io/auth0/auth0/0.2.0/darwin_amd64/terraform-provider-auth0_v0.2.0
...
```

Expand All @@ -39,39 +41,63 @@ terraform {
}
```

## Running tests
## Documentation

The documentation found in the [docs](./docs) folder is generated using
[terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs).
Do not edit files within this folder manually.

Run `make docs` to regenerate documentation for newly added resources and schema attributes or if changes are needed to
existing schemas.

```shell
make docs
```

## Running the Tests

The tests can be run using the following make commands:

To run the tests use the `make test` command. This will make use of the pre-recorded http interactions found in the
[recordings](./test/data/recordings) folder. To add new recordings run the tests against an Auth0 tenant
individually using the following env vars `AUTH0_HTTP_RECORDINGS=on TF_ACC=true`.
- `make test-unit` - runs all the unit tests.
- `make test-acc` - runs the tests with http recordings. To run a specific test pass the `FILTER` var. Usage `make test-acc FILTER="TestAccResourceServer"`.
- `make test-acc-e2e` - runs the tests against a real Auth0 tenant. To run a specific test pass the `FILTER` var. Usage `make test-acc-e2e FILTER="TestAccResourceServer"`.

To run the tests against an Auth0 tenant, use the `make test-acc-e2e` command. Start by creating an
To run the tests against an Auth0 tenant start by creating an
[M2M app](https://auth0.com/docs/applications/set-up-an-application/register-machine-to-machine-applications) in the
tenant, that has been authorized to call the Management API and has all the required permissions.
tenant, that has been authorized to request access tokens for the Management API and has all the required permissions.

Then set the following environment variables:
Then set the following environment variables on your machine:

* `AUTH0_DOMAIN`: The **Domain** of the M2M app
* `AUTH0_CLIENT_ID`: The **Client ID** of the M2M app
* `AUTH0_CLIENT_SECRET`: The **Client Secret** of the M2M app
* `AUTH0_DEBUG`: Set to `true` to call the Management API in debug mode, which dumps the HTTP requests and responses to
the output
* `AUTH0_DEBUG`: Set to `true` to call the Management API in debug mode, which dumps the HTTP requests and responses to the output

**Note:** The e2e acceptance tests make calls to a real Auth0 tenant, and create real resources. Certain tests also
require a paid Auth0 subscription to be able to run successfully, e.g. `TestAccCustomDomain` and the ones starting with
`TestAccLogStream*`.
> **Note**
> The http test recordings can be found in the [recordings](./test/data/recordings) folder.
**Note:** At the time of writing, the following configuration steps are also required for the test tenant:
> **Warning**
> The e2e acceptance tests make calls to a real Auth0 tenant, and create real resources.
> Certain tests also require a paid Auth0 subscription to be able to run successfully,
> e.g. `TestAccCustomDomain` and the ones starting with `TestAccLogStream*`.
* The `Username-Password-Authentication` connection must have _Requires Username_ option enabled for the user tests to
> **Note**
> At the time of writing, the following configuration steps are also required for the test tenant:
> - The `Username-Password-Authentication` connection must have _Requires Username_ option enabled for the user tests to
successfully run.

## Documentation
## Adding New HTTP Test Recordings

The documentation found in the [docs](./docs) folder is generated using
[terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs). Please run `make docs` to regenerate
documentation for newly added resources or schema attributes.
To add new http test recordings or to regenerate old ones you can make use of the `make test-acc-record` command.

```sh
make docs
```
> **Warning**
> If you need to regenerate an old recording, make sure to delete the corresponding recording file first.
To add only one specific http test recording pass the `FILTER` var, e.g. `make test-acc-record FILTER="TestAccResourceServer"`.

> **Warning**
> Recording a new http test interaction will make use of a real Auth0 test tenant.
## Resetting the Test Tenant

All resources created through running the tests against an Auth0 Tenant can be removed by running `make test-sweep`.

0 comments on commit 80cce72

Please sign in to comment.