You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+71-61Lines changed: 71 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,11 +10,14 @@ Before submitting an issue or a pull request, please search the repository for e
10
10
11
11
## Submitting a pull request
12
12
13
-
0. Fork and clone the repository.
14
-
0. Create a new branch: `git switch -c my-branch-name`.
15
-
0. Make your change, add tests, and make sure the tests still pass.
16
-
0. Push to your fork and submit a pull request.
17
-
0. Pat yourself on the back and wait for your pull request to be reviewed and merged.
13
+
1. Fork and clone the repository.
14
+
2. Create a new branch: `git switch -c my-branch-name`.
15
+
3. Make your change, add tests, and make sure the tests still pass.
16
+
4. Run `make docs-lint` to check if the documentation is up to date.
17
+
5. Update the documentation templates if needed.
18
+
6. Run `make docs-generate` to generate changes to the documentation.
19
+
7. Push to your fork and submit a pull request.
20
+
8. Pat yourself on the back and wait for your pull request to be reviewed and merged.
18
21
19
22
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
20
23
@@ -33,26 +36,31 @@ This section describes a typical sequence performed when developing locally. Ful
33
36
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:
34
37
35
38
- If you haven't already, [create a GitHub organization you can use for testing](#github-organization).
36
-
- 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.
37
-
- 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.
38
-
- You _must_ make sure that the "Template Repository" item in Settings is checked for this repo.
39
+
- 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.
40
+
- 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.
41
+
- You _must_ make sure that the "Template Repository" item in Settings is checked for this repo.
39
42
- If you haven't already, generate a Personal Access Token (PAT) for authenticating your test runs.
40
43
- Export the necessary configuration for authenticating your provider with GitHub
44
+
41
45
```sh
42
46
export GITHUB_TOKEN=<token of a user with an organization account>
43
47
export GITHUB_ORGANIZATION=<name of an organization>
44
48
```
49
+
45
50
- Build the project with `make build`
46
51
- 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.
47
52
48
53
### Local Development Iteration
49
54
50
55
1. Write a test describing what you will fix. See [`github_label`](./github/resource_github_issue_label_test.go) for an example format.
51
-
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.
56
+
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.
57
+
52
58
```sh
53
59
TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubIssueLabel
54
60
```
61
+
55
62
1. Align the resource's implementation to your test case and observe it pass:
63
+
56
64
```sh
57
65
TF_ACC=1 go test -v ./... -run ^TestAccGithubIssueLabel
58
66
```
@@ -67,27 +75,29 @@ Println debugging can easily be used to obtain information about how code change
67
75
68
76
If a full debugger is desired, VSCode may be used. In order to do so,
69
77
70
-
0. Create a launch.json file with this configuration:
78
+
1. Create a launch.json file with this configuration:
79
+
71
80
```json
72
81
{
73
-
"name": "Attach to Process",
74
-
"type": "go",
75
-
"request": "attach",
76
-
"mode": "local",
77
-
"processId": 0,
82
+
"name": "Attach to Process",
83
+
"type": "go",
84
+
"request": "attach",
85
+
"mode": "local",
86
+
"processId": 0,
78
87
}
79
88
```
89
+
80
90
Setting a `processId` of 0 allows a dropdown to select the process of the provider.
81
91
82
-
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.
92
+
1. 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.
83
93
84
-
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/`.
94
+
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/`.
85
95
86
-
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.
96
+
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](#using-a-local-version-of-the-provider) section.
87
97
88
-
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.
98
+
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.
89
99
90
-
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.
100
+
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.
91
101
92
102
93
103
## Manual Testing
@@ -121,7 +131,7 @@ provider_installation {
121
131
}
122
132
```
123
133
124
-
See https://www.terraform.io/docs/cli/config/config-file.html for more details.
134
+
See <https://www.terraform.io/docs/cli/config/config-file.html> for more details.
125
135
126
136
When running examples, you should spot the following warning to confirm you are using a local build:
127
137
@@ -179,45 +189,45 @@ This may come in handy when debugging both acceptance and manual testing.
179
189
180
190
```json
181
191
{
182
-
// for information on how to debug the provider, see the CONTRIBUTING.md file
183
-
"version": "0.2.0",
184
-
"configurations": [
185
-
{
186
-
"name": "Launch test function",
187
-
"type": "go",
188
-
"request": "launch",
189
-
"mode": "test",
190
-
// note that the program file must be in the same package as the test to run,
191
-
// though it does not necessarily have to be the file that contains the test.
0 commit comments