From ba3f6747cb21d199be61bdbb98c9bbc86047b329 Mon Sep 17 00:00:00 2001 From: David John Coleman II Date: Mon, 19 Sep 2022 11:27:55 -0500 Subject: [PATCH 1/2] updating developer docs with more helpful setup information --- README.md | 88 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 69 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9f3e72e14..04084feea 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ - [Terraform](https://www.terraform.io/downloads.html) 0.12.x - [Go](https://golang.org/doc/install) 1.11 (to build the provider plugin) -## Building The Provider +## Building the Provider -Clone repository to: `$GOPATH/src/github.com/terraform-providers/terraform-provider-pagerduty` +Clone repository to: `$GOPATH/src/github.com/PagerDuty/terraform-provider-pagerduty` ```sh $ mkdir -p $GOPATH/src/github.com/PagerDuty; cd $GOPATH/src/github.com/PagerDuty @@ -26,28 +26,78 @@ Enter the provider directory and build the provider ```sh $ cd $GOPATH/src/github.com/PagerDuty/terraform-provider-pagerduty $ make build -``` - -## Using the provider - -Please refer to https://registry.terraform.io/providers/PagerDuty/pagerduty/latest/docs for -examples on how to use the provider and detailed documentation about the -Resources and Data Sources the provider has. - -## Developing the Provider - -If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.11+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`. - -To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. - -```sh -$ make build ... $ $GOPATH/bin/terraform-provider-pagerduty ... ``` -### Testing +This will build the provider and put the provider binary in the `$GOPATH/bin` directory. + +## Usage + +Please refer to Terraform docs for [PagerDuty Provider](https://registry.terraform.io/providers/PagerDuty/pagerduty/latest/docs) +for examples on how to use the provider and detailed documentation about the Resources and Data Sources the provider has. + +## Development + +### Setup Local Environment + +Before developing the provider, ensure that you have go correctly installed. + +* Install [Go](http://www.golang.org) on your machine (version 1.11+ is *required*). +* Correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`. + +### Setup Local PagerDuty Provider + +Make changes to the PagerDuty provider and post a pull request for review. + +1. [Create a fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the **upstream** repository `https://github.com/PagerDuty/terraform-provider-pagerduty` +2. Clone the new **origin** repository to your local go src path: `$GOPATH/src/github.com//terraform-provider-pagerduty` +3. optionally make development easier by setting the [**upstream**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork) repository + ``` + $ git remote add upstream git@github.com:PagerDuty/terraform-provider-pagerduty.git + ``` +4. Make any changes on your local machine and post a PR to the **upstream** repository + +### Run Dev Build with Local Terraform Module + +> Note: Development overrides work only in Terraform v0.14 and later. Using a dev_overrides block in your CLI configuration will cause Terraform v0.13 to reject the configuration as invalid. + +1. Build the provider with your latest changes. (See [Building the Provider](https://github.com/PagerDuty/terraform-provider-pagerduty#building-the-provider)) +2. Override the pagerduty provider with your local build. (See [Development Overrides for Provider Developers](https://www.terraform.io/cli/config/config-file#development-overrides-for-provider-developers)) + * Create the file `$HOME/.terraformrc` and paste the following content into it. Be sure to change the path to wherever your binary is located. It is currently set to the default for go builds. + ```terraform + provider_installation { + dev_overrides { + "pagerduty/pagerduty" = "///go/bin" + } + direct {} + } + ``` +3. Goto a local terraform module and start running terraform. (See [Using the Provider](https://github.com/PagerDuty/terraform-provider-pagerduty#using-the-provider)). You may need to first install the latest module and provider + versions allowed within the new configured constraints. Verify with the below warning message. + ```sh + $ terraform init -upgrade + $ terraform plan + ... + │ Warning: Provider development overrides are in effect + ``` +4. See `api_url_override` from Terraform docs for [PagerDuty Provider](https://registry.terraform.io/providers/PagerDuty/pagerduty/latest/docs#argument-reference) to set a custom proxy endpoint as PagerDuty client api url overriding service_region setup. + +### Setup local logs + +1. See [Debugging Terraform](https://www.terraform.io/internals/debugging). Either add this to your shell's profile + (example: `~/.bashrc`), or just execute these commands: + ``` + export TF_LOG=trace + export TF_LOG_PATH="/PATH/TO/YOUR/LOG_FILE.log" + ``` +2. stream logs + ``` + $ tail -f /PATH/TO/YOUR/LOG_FILE.log + ``` + +## Testing In order to test the provider, you can simply run `make test`. From 8db09cc87593e16268798ac83d9b946a8ce83282 Mon Sep 17 00:00:00 2001 From: David John Coleman II Date: Tue, 20 Sep 2022 11:20:30 -0500 Subject: [PATCH 2/2] capitalizes title --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 04084feea..730a10917 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Make changes to the PagerDuty provider and post a pull request for review. ``` 4. See `api_url_override` from Terraform docs for [PagerDuty Provider](https://registry.terraform.io/providers/PagerDuty/pagerduty/latest/docs#argument-reference) to set a custom proxy endpoint as PagerDuty client api url overriding service_region setup. -### Setup local logs +### Setup Local Logs 1. See [Debugging Terraform](https://www.terraform.io/internals/debugging). Either add this to your shell's profile (example: `~/.bashrc`), or just execute these commands: