Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
231 lines (163 loc) · 10.9 KB

CONTRIBUTING.md

File metadata and controls

231 lines (163 loc) · 10.9 KB

Contributing

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential to keep it great.

Contributions to this project are released to the public under the project's open source license.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Before submitting an issue or a pull request, please search the repository for existing content. Issues and PRs with multiple comments, reactions, and experience reports increase the likelihood of a merged change.

Submitting a pull request

  1. Fork and clone the repository.
  2. Create a new branch: git switch -c my-branch-name.
  3. Make your change, add tests, and make sure the tests still pass.
  4. Push to your fork and submit a pull request.
  5. Pat yourself on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Allow your pull request to receive edits by maintainers.
  • Discuss your changes with the community in an issue.
  • Write tests.
  • Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, please submit them as separate pull requests.
  • Write a good commit message.

Quick End-To-End Example

This section describes a typical sequence performed when developing locally. Full details of available tooling are available in the section on Manual Testing.

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 real 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: you 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-template-module. The 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.

  • Export the necessary configuration for authenticating your provider with GitHub

    export GH_TEST_AUTH_MODE="organization"
export GITHUB_OWNER="<name of an organization>"
export GITHUB_USERNAME="<username of the user who created the token>"
export GITHUB_TOKEN="<token of a user with an organization account>"

  • Build the project with make build

  • Try an example test run from the default (main) branch, like TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubRepositories. All those tests should pass.

Local Development Iteration

  1. Write a test describing what you will fix. See github_label for an example format.
  2. 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.
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:
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 should be 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.

Debugging the terraform provider

Println debugging can easily be used to obtain information about how code changes perform. If the TF_LOG=DEBUG level is set, calls to log.Printf("[DEBUG] your message here") will be printed in the program's output.

If a full debugger is desired, VSCode may be used. In order to do so,

  1. Create a launch.json file with this configuration:
{
 "name": "Attach to Process",
 "type": "go",
 "request": "attach",
 "mode": "local",
 "processId": 0,
}

Setting a processId of 0 allows a dropdown to select the process of the provider.

  1. Add a sleep call (e.g. time.Sleep(10 * time.Second)) in the func providerConfigure(p *schema.Provider) schema.ConfigureFunc before the immediate return call. This will allow time to connect the debugger while the provider is initializing, before any critical logic happens.

  2. Build the terraform provider with debug flags enabled and copy it to the appropriate bin folder with a command like go build -gcflags="all=-N -l" -o ~/go/bin/.

  3. Create or edit a dev.tfrc that points toward the newly-built binary, and export the TF_CLI_CONFIG_FILE variable to point to it. Further instructions on this process may be found in the Building the provider section.

  4. Run a terraform command (e.g. terraform apply). While the provider pauses on initialization, go to VSCode and click "Attach to Process". In the search box that appears, type terraform-provi and select the terraform provider process.

  5. The debugger is now connected! During a typical terraform command, the plugin will be invoked multiple times. If the debugger disconnects and the plugin is invoked again later in the run, the developer will have to re-attach each time as the process ID changes.

Manual Testing

Manual testing should be performed on each PR opened in order to validate the provider's correct behavior and discover any regressions. Our automated testing is in an unhealthy spot at this point unfortunately, so extra care is required with manual testing. See issue #1414 for more details.

Using a local version of the provider

Build the provider and specify the output directory:

go build -gcflags="all=-N -l" -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:

export TF_CLI_CONFIG_FILE=path/to/project/examples/dev.tfrc

An example file is available in our examples directory and resembles:

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:

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

Environment variable reference

Commonly required environment variables are listed below:

# Enable debug logging
export TF_LOG=DEBUG

# Enables acceptance tests
export TF_ACC="1"

# Configure the URL override for GHES.
export GITHUB_BASE_URL=

# Configure acceptance testing mode; one of anonymous, individual, organization, team or enterprise. If not set will default to anonymous
export GH_TEST_AUTH_MODE=

# Configure authentication for testing
export GITHUB_OWNER=
export GITHUB_USERNAME=
export GITHUB_TOKEN=

# Configure user level values
export GH_TEST_USER_REPOSITORY=

# Configure values for the organization under test
export GH_TEST_ORG_USER=
export GH_TEST_ORG_SECRET_NAME=
export GH_TEST_ORG_REPOSITORY=
export GH_TEST_ORG_TEMPLATE_REPOSITORY=
export GH_TEST_ORG_APP_INSTALLATION_ID=

# Configure external (non-org) users
export GH_TEST_EXTERNAL_USER=
export GH_TEST_EXTERNAL_USER_TOKEN=
export GH_TEST_EXTERNAL_USER2=

# Configure values for the enterprise under test
export GH_TEST_ENTERPRISE_EMU_GROUP_ID=

# Configure test options
export GH_TEST_ADVANCED_SECURITY=

# Configure if the enterprise is an EMU enterprise
export GH_TEST_ENTERPRISE_IS_EMU=

There are also a small amount of unit tests in the provider. Due to the nature of the provider, such tests are currently only recommended for exercising functionality completely internal to the provider. These may be executed by running make test.

GitHub Organization

If you do not have an organization already that you are comfortable running tests against, you will need to create one. 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.

Make sure that your organization has a terraform-template-module repository (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 feature, please contact a maintainer as special arrangements can be made for your convenience.

Example .vscode/settings.json file

To run acceptance tests the TF_ACC environment variable must be set. Below is an example settings.json file for VSCode that sets this variable and the other necessary environment variables when running tests from the editor.

{
  "go.testEnvVars": {
    "TF_ACC": "1",
    "GITHUB_TOKEN": "<TOKEN>",
    "GITHUB_BASE_URL": "https://api.github.com/",
    "GITHUB_ENTERPRISE_SLUG": "",
    "GITHUB_OWNER": "<ORGANIZATION>",
    "GITHUB_USERNAME": "<USERNAME>",
    "GH_TEST_AUTH_MODE": "organization",
    "GH_TEST_USER_REPOSITORY": "",
    "GH_TEST_ORG_USER": "",
    "GH_TEST_ORG_SECRET_NAME": "",
    "GH_TEST_ORG_REPOSITORY": "",
    "GH_TEST_ORG_TEMPLATE_REPOSITORY": "",
    "GH_TEST_ORG_APP_INSTALLATION_ID": "",
    "GH_TEST_EXTERNAL_USER": "",
    "GH_TEST_EXTERNAL_USER_TOKEN": "",
    "GH_TEST_EXTERNAL_USER2": "",
    "GH_TEST_ADVANCED_SECURITY": "false",
  },
  "go.testTimeout": "3600s",
  "go.testFlags": [
    "-v",
    "-count=1",
  ]
}