From 80cce7224e75d3476b1ba7f14b25ac4bbf1b777a Mon Sep 17 00:00:00 2001 From: Sergiu Ghitea <28300158+sergiught@users.noreply.github.com> Date: Fri, 3 Feb 2023 11:09:27 +0100 Subject: [PATCH] Update CONTRIBUTING --- CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++------------------ 1 file changed, 60 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf8c40a3a..21c492bd8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 ... ``` @@ -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`.