diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6b22991..b4ef66ef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,16 +20,16 @@ To run the Go tests and check test coverage run the following command: go test -v ./... -cover ``` -## Installing plugin locally +## Installing the Provider Locally -Refer to the following sections of the Terraform's "Custom Framework Providers" tutorial to install this plugin locally: +Refer to the following sections of the Terraform's "Custom Framework Providers" tutorial to install this provider locally: - [Prepare Terraform for local provider install](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider#prepare-terraform-for-local-provider-install) - [Locally install provider and verify with Terraform](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider#locally-install-provider-and-verify-with-terraform) -## Using plugin locally +## Using the Provider Locally -In your Terraform configuration you will need to specify the `op` plugin with: +In your Terraform configuration you will need to specify the `onepassword` provider with: ```tf terraform { @@ -48,6 +48,37 @@ provider "onepassword" { After copying a newly-built version of the provider to the plugins directory you will have to run `terraform init` again. If you forget to do this then Terraform will error out and tell you to do so. +## Debugging + +Ensure that the `dev_overrides` block was added to your `~/.terraformrc` file, using `"1Password/onepassword"` as the source. Refer to the [Installing the Provider Locally](#installing-the-provider-locally) section for instructions. + +Build the provider without optimizations enabled: + +```sh +go build -gcflags="all=-N -l" . +``` + +Start a Delve debugging session: + +```sh +dlv debug . -- --debug +Type 'help' for list of commands. +(dlv) continue +``` + +**Note**: Editors like GoLand can be configured to start a debugging session as well. Just be sure to pass the `--debug` flag as a program argument. + +If a debugging session was started properly, the provider should print the following output to `stdout`: + +```sh +Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var: + + TF_REATTACH_PROVIDERS='{"1Password/onepassword":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}' + +``` + +Copy the line starting with `TF_REATTACH_PROVIDERS` from your provider's output. Either export it, or prefix every Terraform command with it, and run Terraform as usual. Any breakpoints you have set will halt execution and show you the current variable values. + ## Generating Documentation Documentation is generated for the provider using [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs). This plugin uses the schema `Description` field in conjunction with the contents of the `/templates` and `/examples` folders to generate the `/docs` content. @@ -57,3 +88,7 @@ To regenerate the `/docs` Markdown run: ```sh go generate ``` + +## Sign Your Commits + +To get your PR merged, we require you to sign your commits. Fortunately, this has become very easy to [set up](https://developer.1password.com/docs/ssh/git-commit-signing/)!