Refresh CONTRIBUTING Documentation (#682)

* refresh contributing docs

* add quick instructions

* add updates for newer versions of terraform

Author: Jeremy Udit

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contributing
+# Contributing
 
 Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
 
@@ -22,14 +22,38 @@ Here are a few things you can do that will increase the likelihood of your pull
 - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
 - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
+## Quick End-To-End Example
+
+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
+  ```sh
+  export GITHUB_TOKEN=<token of a user with an organization account>
+  export GITHUB_ORGANIZATION=<name of an organization>
+  ```
+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
+```
+1. Align the resource's implementation to your test case and observe it pass:
+```sh
+TF_ACC=1  go test -v   ./... -run ^TestAccGithubIssueLabel
+```
+
+Note that some resources still use a previous format that is incompatible with automated test runs, which depend on using the `skipUnlessMode` helper. When encountering these resources, tests are rewritten to the latest format.
+
+Also note that there is no build / `terraform init` / `terraform plan` sequence here.  It is uncommon to run into a bug or feature that requires iteration without using tests. When these cases arise, the `examples/` directory is used to approach the problem, which is detailed in the next section.
+
 ## Automated And Manual Testing
 
 ### Overview
 
-When raising a pull request against this project, automated tests will be launched to run our test suite.
+When raising a pull request against this project, automated tests will be launched to run a subset of our test suite.
 
-In line with Terraform Provider testing best practices, these tests exercise against a live, public GitHub deployment (referred to as `dotcom`). Tests may also run against an Enterprise GitHub deployment (referred to as `ghes`), which is sometimes available during parts of a month. If your change requires testing against a specific version of GitHub, please let a maintainer know and this may be arranged.
+Full acceptance testing is run [daily][acc-daily]. In line with Terraform Provider testing best practices, these tests exercise against a live, public GitHub deployment (referred to as `dotcom`). Tests may also run against an Enterprise GitHub deployment (referred to as `ghes`), which is sometimes available during parts of a month. If your change requires testing against a specific version of GitHub, please let a maintainer know and this may be arranged.
 
+Partial acceptance testing can be run manually by creating a branch prefixed with `test/`.  Simple detection of changes and related test files is performed and a subset of acceptance tests are run against commits to these branches. This is a useful workflow for reviewing PRs submitted by the community, but local testing is preferred for contributors while iterating towards publishing a PR.
 
 ### Building The Provider
 
@@ -38,18 +62,47 @@ Clone the provider
 $ git clone [email protected]:integrations/terraform-provider-github.git
 ```
 
-Enter the provider directory and build the provider
+Enter the provider directory and build the provider while specifying an output directory:
 
 ```sh
-$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-github
-$ make build
-# or if you're on a mac:
-$ gnumake build
+$ go build -o ~/go/bin/
+```
+
+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
+export TF_CLI_CONFIG_FILE=path/to/project/examples/dev.tfrc
+```
+
+An example file is available in our `examples` directory and resembles:
+
+```hcl
+provider_installation {
+  dev_overrides {
+    "integrations/github" = "~/go/bin/"
+  }
+
+  direct {}
+}
+```
+
+See https://www.terraform.io/docs/cli/config/config-file.html for more details.
+
+When running examples, you should spot the following warning to confirm you are using a local build:
+
+```console
+Warning: Provider development overrides are in effect
+
+The following provider development overrides are set in the CLI configuration:
+ - integrations/github in /Users/jcudit/go/bin
 ```
 
 ### 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`.
+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 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.
 
 To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
 
@@ -81,11 +134,23 @@ $ go test -v   ./... -run TestAccProviderConfigure
 
 Commonly required environment variables are listed below:
 
-```console
+```sh
+# enable debug logging
 export TF_LOG=DEBUG
+
+# enable testing of organization scenarios instead of individual or anonymous
 export GITHUB_ORGANIZATION=
-export GITHUB_BASE_URL=
+
+# enable testing of individual scenarios instead of organizaiton or anonymous
 export GITHUB_OWNER=
+
+# enable testing of enterprise appliances
+export GITHUB_BASE_URL=
+
+# leverage helper accounts for tests requiring them
+# examples include: 
+# - https://github.com/github-terraform-test-user
+# - https://github.com/terraformtesting
 export GITHUB_TEST_OWNER=
 export GITHUB_TEST_ORGANIZATION=
 export GITHUB_TEST_USER_TOKEN=
@@ -110,38 +175,15 @@ Once the token has been created, it must be exported in your environment as `GIT
 
 ### GitHub Organization
 
-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_OWNER`.
+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`.
 
 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.
 
-### Test Repositories
-
-In the pasts, tests required pre-existing repositories. The current test suite has been refreshed to have less dependencies like this. Developers would previously have had to set up the following fixtures manually:
-
-In the organization you are using above, create the following test repositories:
-
-* `test-repo`
-  * The description should be `Test description, used in GitHub Terraform provider acceptance test.`
-  * The website url should be `http://www.example.com`
-  * Create two topics within the repo named `test-topic` and `second-test-topic`
-  * In the repo settings, make sure all features and merge button options are enabled.
-  * Create a `test-branch` branch
-* `test-repo-template`
-  * Configure the repository to be a [Template repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)
-  * Create a release on the repository with `tag = v1.0`
-
-Export an environment variable corresponding to `GITHUB_TEMPLATE_REPOSITORY=test-repo-template`.
-
-### GitHub Users
-
-Export your github username (the one you used to create the personal access token above) as `GITHUB_TEST_USER`. You may need to export a different github username as `GITHUB_TEST_COLLABORATOR`. Please note that these usernames cannot be the same as each other, and both of them must be real github usernames. The collaborator user does not need to be added as a collaborator to your test repo or organization, but as the acceptance tests do real things (and will trigger some notifications for this user), you should probably make sure the person you specify knows that you're doing this just to be nice. You can also export `GITHUB_TEST_COLLABORATOR_TOKEN` in order to test the invitation acceptance.
-
-Additionally the user exported as `GITHUB_TEST_USER` should have a public email address configured in their profile; this should be exported as `GITHUB_TEST_USER_EMAIL` and the Github name exported as `GITHUB_TEST_USER_NAME` (this could be different to your GitHub login).
-
-Finally, export the ID of the release created in the template repository as `GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID`
-
 ## Resources
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
 - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
 - [GitHub Help](https://help.github.com)
+
+
+[acc-daily]: https://github.com/integrations/terraform-provider-github/actions?query=workflow%3A%22Acceptance+Tests+%28All%29%22

examples/dev.tfrc

@@ -0,0 +1,7 @@
+provider_installation {
+  dev_overrides {
+    "integrations/github" = "~/go/bin/"
+  }
+
+  direct {}
+}