From 31f9ac564eb7f6be787066f2e23024dbab95db36 Mon Sep 17 00:00:00 2001 From: Keegan Campbell Date: Sat, 3 Apr 2021 08:48:27 -0700 Subject: [PATCH 1/6] Initial commit of contributing.md updates --- CONTRIBUTING.md | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3eed1ed28b..234535d443 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,12 +26,30 @@ Here are a few things you can do that will increase the likelihood of your pull This section describes a typical sequence performed when developing locally. Full details of available tooling are available in the next section on [Automated And Manual Testing](#automated-and-manual-testing). -1. Export necessary configuration for authenticating your provider with GitHub +### Local Development Setup + +Once you have the repository cloned, there's a couple of additional steps you'll need to take. Since most of the testing is acceptance or integration testing, we need to manipulate GitHub resources in order to run it. Useful setup steps are listed below: + +- If you haven't already, create a GitHub organization you can use for testing. + - Optional: some may find it beneficial to create a test user as well in order to avoid potential rate-limiting issues on your main account. + - See [here](#github-organization) for further instructions on creating an organization. + - Your organization _must_ have a repository called `terraform-module-template`. + - See [this repo](https://github.com/terraformtesting/terraform-template-module) for an example you can clone. + - You _must_ make sure that the "Template Repository" item in Settings is checked for this repo. +- If you haven't already, generate a Personal Access Token (PAT) for authenticating your test runs. + - See [here](#github-personal-access-token) for instructions and scope requirements. +- Export the necessary configuration for authenticating your provider with GitHub ```sh export GITHUB_TOKEN= export GITHUB_ORGANIZATION= ``` -1. Write a test describing what you will fix. See [`github_label`](./github/resource_github_issue_label_test.go) for an example format. +- Build the project with `make build` +- Try an example test run off of the default branch. + - For example, you should see all tests pass when running `TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubRepositories` from the main branch. + +### Local Development Iteration + +1. Write a test describing what you will fix. See [`github_label`](./github/resource_github_issue_label_test.go) for an example format. 1. Run your test and observe it fail. Enabling debug output allows for observing the underlying requests and responses made as well as viewing state (search `STATE:`) generated during the acceptance test run. ```sh TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubIssueLabel @@ -68,7 +86,7 @@ Enter the provider directory and build the provider while specifying an output d $ go build -o ~/go/bin/ ``` -This enables verifying your locally built provider using examples available in the `examples/` directory. +This enables verifying your locally built provider using examples available in the `examples/` directory. Note that you will first need to configure your shell to map our provider to the local build: ```sh @@ -100,7 +118,7 @@ The following provider development overrides are set in the CLI configuration: ### 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*). +If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.13+ is *required*). You may also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`. Recent Go releases may have removed the need for this step however. @@ -148,7 +166,7 @@ export GITHUB_OWNER= export GITHUB_BASE_URL= # leverage helper accounts for tests requiring them -# examples include: +# examples include: # - https://github.com/github-terraform-test-user # - https://github.com/terraformtesting export GITHUB_TEST_OWNER= @@ -177,6 +195,8 @@ Once the token has been created, it must be exported in your environment as `GIT If you do not have an organization already that you are comfortable running tests against, you will need to [create one](https://help.github.com/en/articles/creating-a-new-organization-from-scratch). The free "Team for Open Source" org type is fine for these tests. The name of the organization must then be exported in your environment as `GITHUB_ORGANIZATION`. +Make sure that your organization has a `terraform-module-template` repository (see [here](https://github.com/terraformtesting/terraform-template-module) for an example you can clone) and that its "Template repository" item in Settings is checked. + If you are interested in using and/or testing Github's [Team synchronization](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/synchronizing-teams-between-your-identity-provider-and-github) feature, please contact a maintainer as special arrangements can be made for your convenience. ## Resources From ea8517a61fb59bfabd3b2274dfe00a945d4fa90e Mon Sep 17 00:00:00 2001 From: Keegan Campbell Date: Tue, 6 Apr 2021 09:33:01 -0700 Subject: [PATCH 2/6] Update CONTRIBUTING.md Co-authored-by: Issy Long --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 234535d443..bfc86fdaca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,9 +30,8 @@ This section describes a typical sequence performed when developing locally. Ful Once you have the repository cloned, there's a couple of additional steps you'll need to take. Since most of the testing is acceptance or integration testing, we need to manipulate GitHub resources in order to run it. Useful setup steps are listed below: -- If you haven't already, create a GitHub organization you can use for testing. +- If you haven't already, [create a GitHub organization you can use for testing](#github-organization). - Optional: some may find it beneficial to create a test user as well in order to avoid potential rate-limiting issues on your main account. - - See [here](#github-organization) for further instructions on creating an organization. - Your organization _must_ have a repository called `terraform-module-template`. - See [this repo](https://github.com/terraformtesting/terraform-template-module) for an example you can clone. - You _must_ make sure that the "Template Repository" item in Settings is checked for this repo. @@ -206,4 +205,4 @@ If you are interested in using and/or testing Github's [Team synchronization](ht - [GitHub Help](https://help.github.com) -[acc-daily]: https://github.com/integrations/terraform-provider-github/actions?query=workflow%3A%22Acceptance+Tests+%28All%29%22 \ No newline at end of file +[acc-daily]: https://github.com/integrations/terraform-provider-github/actions?query=workflow%3A%22Acceptance+Tests+%28All%29%22 From 7b4b744c86fdead89d214214ba6cb61e10e3f3d6 Mon Sep 17 00:00:00 2001 From: Keegan Campbell Date: Tue, 6 Apr 2021 09:33:18 -0700 Subject: [PATCH 3/6] Update CONTRIBUTING.md Co-authored-by: Issy Long --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bfc86fdaca..7eb27c73b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,8 +32,7 @@ Once you have the repository cloned, there's a couple of additional steps you'll - If you haven't already, [create a GitHub organization you can use for testing](#github-organization). - Optional: some may find it beneficial to create a test user as well in order to avoid potential rate-limiting issues on your main account. - - Your organization _must_ have a repository called `terraform-module-template`. - - See [this repo](https://github.com/terraformtesting/terraform-template-module) for an example you can clone. + - Your organization _must_ have a repository called `terraform-module-template`. The [terraformtesting/terraform-template-module](https://github.com/terraformtesting/terraform-template-module) repo is a good, re-usable example. - You _must_ make sure that the "Template Repository" item in Settings is checked for this repo. - If you haven't already, generate a Personal Access Token (PAT) for authenticating your test runs. - See [here](#github-personal-access-token) for instructions and scope requirements. From 4eef0c4cea26c834859c97e5aa1b2d3f50055141 Mon Sep 17 00:00:00 2001 From: Keegan Campbell Date: Tue, 6 Apr 2021 09:33:28 -0700 Subject: [PATCH 4/6] Update CONTRIBUTING.md Co-authored-by: Issy Long --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7eb27c73b5..120724842f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,8 +34,7 @@ Once you have the repository cloned, there's a couple of additional steps you'll - Optional: some may find it beneficial to create a test user as well in order to avoid potential rate-limiting issues on your main account. - Your organization _must_ have a repository called `terraform-module-template`. The [terraformtesting/terraform-template-module](https://github.com/terraformtesting/terraform-template-module) repo is a good, re-usable example. - You _must_ make sure that the "Template Repository" item in Settings is checked for this repo. -- If you haven't already, generate a Personal Access Token (PAT) for authenticating your test runs. - - See [here](#github-personal-access-token) for instructions and scope requirements. +- If you haven't already, [generate a Personal Access Token (PAT) for authenticating your test runs](#github-personal-access-token). - Export the necessary configuration for authenticating your provider with GitHub ```sh export GITHUB_TOKEN= From 02fbd4bb788171736696545f5a2f359207be9155 Mon Sep 17 00:00:00 2001 From: Keegan Campbell Date: Tue, 6 Apr 2021 09:33:44 -0700 Subject: [PATCH 5/6] Update CONTRIBUTING.md Co-authored-by: Issy Long --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 120724842f..d65ce107e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,8 +41,7 @@ Once you have the repository cloned, there's a couple of additional steps you'll export GITHUB_ORGANIZATION= ``` - Build the project with `make build` -- Try an example test run off of the default branch. - - For example, you should see all tests pass when running `TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubRepositories` from the main branch. +- Try an example test run from the default (`master`) branch, like `TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubRepositories`. All those tests should pass. ### Local Development Iteration From 7067510bd6b9f2e7b5958ab18fa6302a559daae4 Mon Sep 17 00:00:00 2001 From: Keegan Campbell Date: Tue, 6 Apr 2021 09:34:11 -0700 Subject: [PATCH 6/6] Update CONTRIBUTING.md Co-authored-by: Issy Long --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d65ce107e1..9ecbe5a88b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -191,7 +191,7 @@ Once the token has been created, it must be exported in your environment as `GIT If you do not have an organization already that you are comfortable running tests against, you will need to [create one](https://help.github.com/en/articles/creating-a-new-organization-from-scratch). The free "Team for Open Source" org type is fine for these tests. The name of the organization must then be exported in your environment as `GITHUB_ORGANIZATION`. -Make sure that your organization has a `terraform-module-template` repository (see [here](https://github.com/terraformtesting/terraform-template-module) for an example you can clone) and that its "Template repository" item in Settings is checked. +Make sure that your organization has a `terraform-module-template` repository ([terraformtesting/terraform-template-module](https://github.com/terraformtesting/terraform-template-module) is an example you can clone) and that its "Template repository" item in Settings is checked. If you are interested in using and/or testing Github's [Team synchronization](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/synchronizing-teams-between-your-identity-provider-and-github) feature, please contact a maintainer as special arrangements can be made for your convenience.