diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index be9aba9067..ee3555c646 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/checkout@v4 - uses: actions/setup-go@v4 with: - go-version: '1.20.2' + go-version: '1.21' - run: make tools - run: make lint - run: make website-lint diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 08fcb2a2e1..a4b2bb0de0 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -26,6 +26,9 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL diff --git a/.github/workflows/dotcom-acceptance-tests-all.yml b/.github/workflows/dotcom-acceptance-tests-all.yml index 03a8258ec8..887b1dd925 100644 --- a/.github/workflows/dotcom-acceptance-tests-all.yml +++ b/.github/workflows/dotcom-acceptance-tests-all.yml @@ -20,6 +20,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Anonymous) uses: terraformtesting/acceptance-tests@v2.2.0 with: @@ -34,6 +37,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Individual) id: acceptance-tests-individual @@ -63,6 +69,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Organization) id: acceptance-tests-organization diff --git a/.github/workflows/dotcom-acceptance-tests-manual.yml b/.github/workflows/dotcom-acceptance-tests-manual.yml index fe5b3ca829..25e5ef0732 100644 --- a/.github/workflows/dotcom-acceptance-tests-manual.yml +++ b/.github/workflows/dotcom-acceptance-tests-manual.yml @@ -20,6 +20,9 @@ jobs: uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }} + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Anonymous) id: acceptance-tests-anonymous uses: terraformtesting/acceptance-tests@v2.2.0 @@ -48,6 +51,9 @@ jobs: uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }} + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Individual) id: acceptance-tests-individual uses: terraformtesting/acceptance-tests@v2.2.0 @@ -81,6 +87,9 @@ jobs: uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }} + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Organization) id: acceptance-tests-organization diff --git a/.github/workflows/dotcom-acceptance-tests.yml b/.github/workflows/dotcom-acceptance-tests.yml index ead7e8b31b..9b0624c307 100644 --- a/.github/workflows/dotcom-acceptance-tests.yml +++ b/.github/workflows/dotcom-acceptance-tests.yml @@ -28,6 +28,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Individual) uses: terraformtesting/acceptance-tests@v2.2.0 with: @@ -44,6 +47,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Organization) uses: terraformtesting/acceptance-tests@v2.2.0 with: diff --git a/.github/workflows/ghes-acceptance-tests-all.yml b/.github/workflows/ghes-acceptance-tests-all.yml index 3dde9f3886..d569e3b05b 100644 --- a/.github/workflows/ghes-acceptance-tests-all.yml +++ b/.github/workflows/ghes-acceptance-tests-all.yml @@ -32,6 +32,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Anonymous) uses: terraformtesting/acceptance-tests@v2.2.0 with: @@ -47,6 +50,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Individual) id: acceptance-tests-individual @@ -78,6 +84,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Organization) id: acceptance-tests-organization diff --git a/.github/workflows/ghes-acceptance-tests.yml b/.github/workflows/ghes-acceptance-tests.yml index 03c835fb3a..36dd952780 100644 --- a/.github/workflows/ghes-acceptance-tests.yml +++ b/.github/workflows/ghes-acceptance-tests.yml @@ -27,6 +27,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Anonymous) uses: terraformtesting/acceptance-tests@v2.2.0 with: @@ -42,6 +45,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Individual) uses: terraformtesting/acceptance-tests@v2.2.0 with: @@ -59,6 +65,9 @@ jobs: with: ref: ${{ github.event.pull_request.head.ref }} fetch-depth: 2 + - uses: actions/setup-go@v4 + with: + go-version: '1.21' - name: Acceptance Tests (Organization) uses: terraformtesting/acceptance-tests@v2.2.0 with: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 03e71f2b08..bd33c5c059 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -28,7 +28,7 @@ jobs: name: Set up Go uses: actions/setup-go@v4 with: - go-version: 1.18 + go-version: 1.21 - name: Import GPG key id: import_gpg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b676194fb..f1526ef9a6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,49 +1,49 @@ # Contributing -Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great. +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](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). 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/experience reports increase the likelihood of a merged change. +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 -0. Fork and clone the repository -0. Create a new branch: `git checkout -b my-branch-name` -0. Make your change, add tests, and make sure the tests still pass -0. Push to your fork and submit a pull request -0. Pat your self on the back and wait for your pull request to be reviewed and merged. +0. Fork and clone the repository. +0. Create a new branch: `git switch -c my-branch-name`. +0. Make your change, add tests, and make sure the tests still pass. +0. Push to your fork and submit a pull request. +0. 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: -- Discuss your changes with the community in an issue. - 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, consider submitting them as separate pull requests. +- 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](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). +This section describes a typical sequence performed when developing locally. Full details of available tooling are available in the section on [Manual Testing](#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 GitHub resources in order to run it. Useful setup steps are listed below: +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](#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. + - 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](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](#github-personal-access-token). +- 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 ```sh export GITHUB_TOKEN= export GITHUB_ORGANIZATION= ``` - 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. +- 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 @@ -57,7 +57,7 @@ TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubIssueLabel 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. +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. @@ -67,7 +67,7 @@ Println debugging can easily be used to obtain information about how code change If a full debugger is desired, VSCode may be used. In order to do so, -1. create a launch.json file with this configuration: +0. Create a launch.json file with this configuration: ```json { "name": "Attach to Process", @@ -79,38 +79,27 @@ If a full debugger is desired, VSCode may be used. In order to do so, ``` Setting a `processId` of 0 allows a dropdown to select the process of the provider. -2. Add a sleep call (e.g. `time.Sleep(15 * time.Second)`) in the [func providerConfigure(p *schema.Provider](https://github.com/integrations/terraform-provider-github/blob/main/github/provider.go#L176) 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 a 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](#building-the-provider) section. +0. Add a sleep call (e.g. `time.Sleep(10 * time.Second)`) in the [`func providerConfigure(p *schema.Provider) schema.ConfigureFunc`](https://github.com/integrations/terraform-provider-github/blob/cec7e175c50bb091feecdc96ba117067c35ee351/github/provider.go#L274C1-L274C64) before the immediate `return` call. This will allow time to connect the debugger while the provider is initializing, before any critical logic happens. -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. +0. 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`. -5. The debugger is now connected! During a typical terraform command, the plugin may 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. +0. 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](#using-a-local-version-of-the-provider) section. +0. 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. -## Automated And Manual Testing +0. 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. -### Overview -When raising a pull request against this project, automated tests will be launched to run a subset of our test suite. +## Manual Testing -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. +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](https://github.com/integrations/terraform-provider-github/issues/1414) for more details. -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 - -Clone the provider -```sh -$ git clone git@github.com:integrations/terraform-provider-github.git -``` +### Using a local version of the provider -Enter the provider directory and build the provider while specifying an output directory: +Build the provider and specify the output directory: ```sh -$ go build -o ~/go/bin/ +$ go build -gcflags="all=-N -l" -o ~/go/bin ``` This enables verifying your locally built provider using examples available in the `examples/` directory. @@ -143,33 +132,7 @@ 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.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. - -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-github -... -``` - -In order to run the full suite of provider acceptance tests, run `make testacc`. - -*Note:* Acceptance tests create real resources, and often cost money to run. - -```sh -# run all tests through `make` -$ make testacc -# run all tests directly -$ go test -v ./... -# run specific test -$ go test -v ./... -run TestAccProviderConfigure -``` +### Environment variable reference Commonly required environment variables are listed below: @@ -195,25 +158,10 @@ export GITHUB_TEST_ORGANIZATION= export GITHUB_TEST_USER_TOKEN= ``` -See [this project](https://github.com/terraformtesting/acceptance-tests) for more information on how tests are run automatically. +See [this project](https://github.com/terraformtesting/acceptance-tests) for more information on our old system for automated testing. 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 Personal Access Token - -You will need to create a [personal access token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) for -testing. It will need to have the following scopes selected: -* repo -* admin:org -* admin:public_key -* admin:repo_hook -* admin:org_hook -* user -* delete_repo -* admin:gpg_key - -Once the token has been created, it must be exported in your environment as `GITHUB_TOKEN`. - ### 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_ORGANIZATION`. @@ -222,11 +170,51 @@ Make sure that your organization has a `terraform-template-module` repository ([ 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 - -- [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) +### Example .vscode/launch.json file +This may come in handy when debugging both acceptance and manual testing. -[acc-daily]: https://github.com/integrations/terraform-provider-github/actions?query=workflow%3A%22Acceptance+Tests+%28All%29%22 +```json +{ + // for information on how to debug the provider, see the CONTRIBUTING.md file + "version": "0.2.0", + "configurations": [ + { + "name": "Launch test function", + "type": "go", + "request": "launch", + "mode": "test", + // note that the program file must be in the same package as the test to run, + // though it does not necessarily have to be the file that contains the test. + "program": "/home/kfcampbell/github/dev/terraform-provider-github/github/resource_github_team_members_test.go", + "args": [ + "-test.v", + "-test.run", + "^TestAccGithubRepositoryTopics$" // ^ExactMatch$ + ], + "env": { + "GITHUB_TEST_COLLABORATOR": "kfcampbell-terraform-test-user", + "GITHUB_TEST_COLLABORATOR_TOKEN": "ghp_xxx", + "GITHUB_TEST_USER": "kfcampbell", + "GITHUB_TOKEN": "ghp_xxx", + "GITHUB_TEMPLATE_REPOSITORY": "terraform-template-module", + "GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID": "12345678", + // "GITHUB_OWNER": "kfcampbell-terraform-provider", + // "GITHUB_OWNER": "kfcampbell", + "GITHUB_ORGANIZATION": "kfcampbell-terraform-provider", // GITHUB_ORGANIZATION is required for organization integration tests + "TF_CLI_CONFIG_FILE": "/home/kfcampbell/github/dev/terraform-provider-github/examples/dev.tfrc", + "TF_ACC": "1", + "TF_LOG": "DEBUG", + "APP_INSTALLATION_ID": "12345678" + } + }, + { + "name": "Attach to Process", + "type": "go", + "request": "attach", + "mode": "local", + "processId": 0 + } + ] +} +``` diff --git a/README.md b/README.md index 813ddd96bc..00b3a97458 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,12 @@ Terraform Provider GitHub -This project is used to read and write to/from GitHub (repositories, teams, files, etc.) using Terraform. Its Terraform Registry page can be found [here](https://registry.terraform.io/providers/integrations/github/). +This project is used to manipulate GitHub resources (repositories, teams, files, etc.) using Terraform. Its Terraform Registry page can be found [here](https://registry.terraform.io/providers/integrations/github/). ## Requirements - [Terraform](https://www.terraform.io/downloads.html) 0.10.x -- [Go](https://golang.org/doc/install) 1.17.x (to build the provider plugin) +- [Go](https://golang.org/doc/install) 1.19.x (to build the provider plugin) ## Usage @@ -26,4 +26,4 @@ This project uses [Milestones](https://github.com/integrations/terraform-provide ## Support -This is a community-supported project. GitHub Support is not responsible for maintenance. Please engage with the community via Issues for support. +This is a community-supported project. GitHub's SDK team triages issues and PRs each Monday and Friday. Please engage with the community via Issues for support, and PRs are always welcome! diff --git a/RELEASE.md b/RELEASE.md index bda1274e55..2be591e519 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,12 +1,15 @@ ## Release Flow -Since the migration to the [Terraform registry](https://registry.terraform.io/), this repository's maintainers now have -the ability to self-publish Terraform GitHub provider releases. This process uses GitHub Actions -and [`goreleaser`](https://github.com/goreleaser/goreleaser) to build, sign, and upload provider binaries to a GitHub release. +The release process uses GitHub Actions and [`goreleaser`](https://github.com/goreleaser/goreleaser) to build, sign, and upload provider binaries to a GitHub release. The release flow is as follows: 1. Navigate to the [repository's Releases page](https://github.com/integrations/terraform-provider-github/releases) and click "Draft a new release". 1. Create a new tag that makes sense with the project's semantic versioning. + 1. Before releasing a major version, check the following: + - Read [this doc](https://developer.hashicorp.com/terraform/plugin/best-practices/versioning#versioning-specification) for Hashicorp's major release guidance. + - Ensure there hasn't been a major release in the past year. + - Check all [major-release-tagged](https://github.com/integrations/terraform-provider-github/pulls?q=label%3AvNext) PRs and add them to the release branch as appropriate. + - Ensure all applicable schema changes include [schema migration functions](https://github.com/integrations/terraform-provider-github/blob/a361b158a645282a238cdefa5c40ae950556a4a7/github/migrate_github_repository.go#L20) so consumers' state is not disrupted. 1. Auto-generate the release notes. 1. Click "Publish release". 1. GitHub Actions will trigger the release workflow which can be