Skip to content

Commit 3f5125d

Browse files
armsnyderarmsnyder
committed
Add CONTRIBUTING.md
1 parent 28c19f9 commit 3f5125d

File tree

2 files changed

+152
-102
lines changed

2 files changed

+152
-102
lines changed

‎CONTRIBUTING.md

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
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+
## Developing The Provider
52+
53+
You'll first need [Go](http://www.golang.org) installed on your machine (version 1.14+ is *required*).
54+
55+
1. Clone the git repository.
56+
57+
```sh
58+
$ git clone [email protected]:gitlabhq/terraform-provider-gitlab
59+
$ cd terraform-provider-gitlab
60+
```
61+
62+
2. Build the provider with `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
63+
64+
```sh
65+
$ make build
66+
```
67+
68+
### Running Tests
69+
70+
The acceptance tests can run against a Gitlab instance where you have a token with administrator permissions (likely not gitlab.com).
71+
72+
#### Option 1: Run tests against a local Gitlab container with docker-compose
73+
74+
This option is the easiest and requires [docker-compose](https://docs.docker.com/compose/install/) (version 1.13+) to be installed on your machine.
75+
76+
1. Start the Gitlab container. It will take about 5 minutes for the container to become healthy.
77+
78+
```sh
79+
$ make testacc-up
80+
```
81+
82+
2. Run the acceptance tests. The full suite takes 10-20 minutes to run.
83+
84+
```sh
85+
$ make testacc
86+
```
87+
88+
3. Stop the Gitlab container.
89+
90+
```sh
91+
$ make testacc-down
92+
```
93+
94+
#### Option 2: Run tests against your own Gitlab instance
95+
96+
If you have your own hosted Gitlab instance, you can run the tests against it directly.
97+
98+
```sh
99+
$ make testacc GITLAB_TOKEN=example123 GITLAB_BASE_URL=https://example.com/api/v4
100+
```
101+
102+
`GITLAB_TOKEN` must be a valid token for an account with admin privileges.
103+
104+
#### Testing Tips
105+
106+
* **Gitlab Community Edition and Gitlab Enterprise Edition:**
107+
108+
This module supports both Gitlab CE and Gitlab EE. We run tests on Gitlab EE,
109+
but can't run them on pull requests from forks.
110+
111+
Features that only work on one flavour can use the following helpers as
112+
SkipFunc: `isRunningInEE` and `isRunningInCE`. You can see an example of this
113+
for [gitlab_project_level_mr_approvals](gitlab/resource_gitlab_project_level_mr_approvals_test.go)
114+
tests.
115+
116+
* **Run EE tests:**
117+
118+
If you have a `Gitlab-license.txt` you can run Gitlab EE, which will enable the full suite of tests:
119+
120+
```sh
121+
$ make testacc-up SERVICE=gitlab-ee
122+
```
123+
124+
* **Run a single test:**
125+
126+
You can pass a pattern to the `RUN` variable to run a reduced number of tests. For example:
127+
128+
```sh
129+
$ make testacc RUN=TestAccGitlabGroup
130+
```
131+
132+
...will run all tests for the `gitlab_group` resource.
133+
134+
* **Debug a test in an IDE:**
135+
136+
First start the Gitlab container with `make testacc-up`.
137+
Then run the desired Go test as you would normally from your IDE, but configure your run configuration to set these environment variables:
138+
139+
```
140+
GITLAB_TOKEN=ACCTEST1234567890123
141+
GITLAB_BASE_URL=http://127.0.0.1:8080/api/v4
142+
TF_ACC=1
143+
```
144+
145+
* **Useful HashiCorp documentation:**
146+
147+
Refer to [HashiCorp's testing guide](https://www.terraform.io/docs/extend/testing/index.html)
148+
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)