Skip to content

Commit 18f9815

Browse files
armsnyderarmsnyder
authored
Merge pull request #786 from gitlabhq/contributing
Add CONTRIBUTING.md
2 parents ab46cba + 0542688 commit 18f9815

File tree

2 files changed

+156
-102
lines changed

2 files changed

+156
-102
lines changed

‎CONTRIBUTING.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Contributing to GitLab Terraform Provider
2+
3+
Thank you for contributing to this provider! :tada: :heart: :trophy:
4+
5+
Generally we accept any change that adds or changes a Terraform resource that is in line with the [GitLab API](https://docs.gitlab.com/ee/api/api_resources.html). It is always best to [open an issue](https://github.com/gitlabhq/terraform-provider-gitlab/issues/new/choose) before starting on a change.
6+
7+
## Getting Started
8+
9+
Use HashiCorp's [Plugin Development](https://www.terraform.io/plugin) guide as a reference, especially the [Provider Design Principles](https://www.terraform.io/plugin/hashicorp-provider-design-principles).
10+
11+
See the [Developing The Provider](#developing-the-provider) section below for specifics about this GitLab provider.
12+
13+
## PR Checklist
14+
15+
<!--
16+
These are the most common issues in PRs which we have not automated.
17+
-->
18+
19+
For a smooth review process, please run through this checklist before submitting a PR.
20+
21+
1. Resource attributes match 1:1 the names and structure of the API resource in the [GitLab API documentation](https://docs.gitlab.com/ee/api/api_resources.html).
22+
1. [Docs](/docs) are updated with any new resources or attributes, including how to import the resource.
23+
1. New resources should have at minimum a basic test with three steps:
24+
1. Create the resource
25+
1. Update the attributes
26+
1. Import the resource
27+
1. No new `//lintignore` comments that came from copied code. Linter rules are meant to be enforced on new code.
28+
29+
## Guidelines
30+
31+
<!--
32+
These guidelines are specific callouts for issues that come up occasionally but are somewhat niche.
33+
-->
34+
35+
#### Resource ID and Import
36+
37+
Terraform resources have a unique ID (`d.SetId("")`). The ID should be comprised from the URL path variables of the `GET` API for the resource in the [GitLab API documentation](https://docs.gitlab.com/ee/api/api_resources.html), separated by `:`.
38+
39+
For example, a resource for the `GET /projects/:id/environments/:environment_id` API would have the ID `123:456` where `123` is the project ID and `456` is the environment ID.
40+
41+
This makes it very easy to add import functionality, by using
42+
43+
```go
44+
Importer: &schema.ResourceImporter{
45+
State: schema.ImportStatePassthrough,
46+
},
47+
```
48+
49+
See the [importer state function docs](https://www.terraform.io/plugin/sdkv2/resources/import#importer-state-function) for more details.
50+
51+
#### Documentation
52+
53+
At the moment, documentation is handcrafted. Doc pages are located in [/docs](/docs). Please follow the [Terraform doc formatting guidelines](https://www.terraform.io/registry/providers/docs#format) for these pages. The [Terraform doc preview tool](https://registry.terraform.io/tools/doc-preview) is very helpful for previewing the markdown.
54+
55+
## Developing The Provider
56+
57+
You'll first need [Go](http://www.golang.org) installed on your machine (version 1.14+ is *required*).
58+
59+
1. Clone the git repository.
60+
61+
```sh
62+
$ git clone [email protected]:gitlabhq/terraform-provider-gitlab
63+
$ cd terraform-provider-gitlab
64+
```
65+
66+
2. Build the provider with `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
67+
68+
```sh
69+
$ make build
70+
```
71+
72+
### Running Tests
73+
74+
The acceptance tests can run against a Gitlab instance where you have a token with administrator permissions (likely not gitlab.com).
75+
76+
#### Option 1: Run tests against a local Gitlab container with docker-compose
77+
78+
This option is the easiest and requires [docker-compose](https://docs.docker.com/compose/install/) (version 1.13+) to be installed on your machine.
79+
80+
1. Start the Gitlab container. It will take about 5 minutes for the container to become healthy.
81+
82+
```sh
83+
$ make testacc-up
84+
```
85+
86+
2. Run the acceptance tests. The full suite takes 10-20 minutes to run.
87+
88+
```sh
89+
$ make testacc
90+
```
91+
92+
3. Stop the Gitlab container.
93+
94+
```sh
95+
$ make testacc-down
96+
```
97+
98+
#### Option 2: Run tests against your own Gitlab instance
99+
100+
If you have your own hosted Gitlab instance, you can run the tests against it directly.
101+
102+
```sh
103+
$ make testacc GITLAB_TOKEN=example123 GITLAB_BASE_URL=https://example.com/api/v4
104+
```
105+
106+
`GITLAB_TOKEN` must be a valid token for an account with admin privileges.
107+
108+
#### Testing Tips
109+
110+
* **Gitlab Community Edition and Gitlab Enterprise Edition:**
111+
112+
This module supports both Gitlab CE and Gitlab EE. We run tests on Gitlab EE,
113+
but can't run them on pull requests from forks.
114+
115+
Features that only work on one flavour can use the following helpers as
116+
SkipFunc: `isRunningInEE` and `isRunningInCE`. You can see an example of this
117+
for [gitlab_project_level_mr_approvals](gitlab/resource_gitlab_project_level_mr_approvals_test.go)
118+
tests.
119+
120+
* **Run EE tests:**
121+
122+
If you have a `Gitlab-license.txt` you can run Gitlab EE, which will enable the full suite of tests:
123+
124+
```sh
125+
$ make testacc-up SERVICE=gitlab-ee
126+
```
127+
128+
* **Run a single test:**
129+
130+
You can pass a pattern to the `RUN` variable to run a reduced number of tests. For example:
131+
132+
```sh
133+
$ make testacc RUN=TestAccGitlabGroup
134+
```
135+
136+
...will run all tests for the `gitlab_group` resource.
137+
138+
* **Debug a test in an IDE:**
139+
140+
First start the Gitlab container with `make testacc-up`.
141+
Then run the desired Go test as you would normally from your IDE, but configure your run configuration to set these environment variables:
142+
143+
```
144+
GITLAB_TOKEN=ACCTEST1234567890123
145+
GITLAB_BASE_URL=http://127.0.0.1:8080/api/v4
146+
TF_ACC=1
147+
```
148+
149+
* **Useful HashiCorp documentation:**
150+
151+
Refer to [HashiCorp's testing guide](https://www.terraform.io/docs/extend/testing/index.html)
152+
and [HashiCorp's testing best practices](https://www.terraform.io/docs/extend/best-practices/testing.html).

‎README.md

Lines changed: 4 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
<img src="https://www.datocms-assets.com/2885/1629941242-logo-terraform-main.svg" width="600px">
22

3-
Terraform Provider for Gitlab
4-
=============================
3+
# Terraform Provider for Gitlab
54

65
- [Documentation](https://www.terraform.io/docs/providers/gitlab/index.html)
76
- [![Gitter chat](https://badges.gitter.im/hashicorp-terraform/Lobby.png)](https://gitter.im/hashicorp-terraform/Lobby)
@@ -11,107 +10,10 @@ Terraform Provider for Gitlab
1110
- [![Acceptance Tests](https://github.com/gitlabhq/terraform-provider-gitlab/workflows/Acceptance%20Tests/badge.svg?branch=master)](https://github.com/gitlabhq/terraform-provider-gitlab/actions?query=workflow%3A%22Acceptance+Tests%22+branch%3Amaster)
1211
- ![Website Build](https://github.com/gitlabhq/terraform-provider-gitlab/workflows/Website%20Build/badge.svg?branch=master)
1312

14-
Requirements
15-
------------
13+
## Requirements
1614

1715
- [Terraform](https://www.terraform.io/downloads.html) >= 0.12.x
18-
- [Go](https://golang.org/doc/install) >= 1.14 (to build the provider plugin)
1916

20-
## Developing The Provider
17+
## Contributing
2118

22-
If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.14+ is *required*).
23-
24-
1. Clone the git repository.
25-
26-
```sh
27-
$ git clone [email protected]:gitlabhq/terraform-provider-gitlab
28-
$ cd terraform-provider-gitlab
29-
```
30-
31-
2. Build the provider with `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
32-
33-
```sh
34-
$ make build
35-
```
36-
37-
### Running Tests
38-
39-
The acceptance tests can run against a Gitlab instance where you have a token with administrator permissions (likely not gitlab.com).
40-
41-
#### Option 1: Run tests against a local Gitlab container with docker-compose
42-
43-
This option is the easiest and requires [docker-compose](https://docs.docker.com/compose/install/) (version 1.13+) to be installed on your machine.
44-
45-
1. Start the Gitlab container. It will take about 5 minutes for the container to become healthy.
46-
47-
```sh
48-
$ make testacc-up
49-
```
50-
51-
2. Run the acceptance tests. The full suite takes 10-20 minutes to run.
52-
53-
```sh
54-
$ make testacc
55-
```
56-
57-
3. Stop the Gitlab container.
58-
59-
```sh
60-
$ make testacc-down
61-
```
62-
63-
#### Option 2: Run tests against your own Gitlab instance
64-
65-
If you have your own hosted Gitlab instance, you can run the tests against it directly.
66-
67-
```sh
68-
$ make testacc GITLAB_TOKEN=example123 GITLAB_BASE_URL=https://example.com/api/v4
69-
```
70-
71-
`GITLAB_TOKEN` must be a valid token for an account with admin privileges.
72-
73-
#### Testing Tips
74-
75-
* **Gitlab Community Edition and Gitlab Enterprise Edition:**
76-
77-
This module supports both Gitlab CE and Gitlab EE. We run tests on Gitlab EE,
78-
but can't run them on pull requests from forks.
79-
80-
Features that only work on one flavour can use the following helpers as
81-
SkipFunc: `isRunningInEE` and `isRunningInCE`. You can see an example of this
82-
for [gitlab_project_level_mr_approvals](gitlab/resource_gitlab_project_level_mr_approvals_test.go)
83-
tests.
84-
85-
* **Run EE tests:**
86-
87-
If you have a `Gitlab-license.txt` you can run Gitlab EE, which will enable the full suite of tests:
88-
89-
```sh
90-
$ make testacc-up SERVICE=gitlab-ee
91-
```
92-
93-
* **Run a single test:**
94-
95-
You can pass a pattern to the `RUN` variable to run a reduced number of tests. For example:
96-
97-
```sh
98-
$ make testacc RUN=TestAccGitlabGroup
99-
```
100-
101-
...will run all tests for the `gitlab_group` resource.
102-
103-
* **Debug a test in an IDE:**
104-
105-
First start the Gitlab container with `make testacc-up`.
106-
Then run the desired Go test as you would normally from your IDE, but configure your run configuration to set these environment variables:
107-
108-
```
109-
GITLAB_TOKEN=ACCTEST1234567890123
110-
GITLAB_BASE_URL=http://127.0.0.1:8080/api/v4
111-
TF_ACC=1
112-
```
113-
114-
* **Useful HashiCorp documentation:**
115-
116-
Refer to [HashiCorp's testing guide](https://www.terraform.io/docs/extend/testing/index.html)
117-
and [HashiCorp's testing best practices](https://www.terraform.io/docs/extend/best-practices/testing.html).
19+
Check out the [CONTRIBUTING.md](/CONTRIBUTING.md) guide for tips on how to contribute and develop the provider.

0 commit comments

Comments
 (0)