Skip to content

Commit 3f74287

Browse files
gigerdogigerdo
committed
Extend CONTRIBUTING.md
1 parent 053b599 commit 3f74287

File tree

2 files changed

+123
-99
lines changed

2 files changed

+123
-99
lines changed

‎CONTRIBUTING.md‎

Lines changed: 121 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,145 @@
1-
# Typical development workflow
1+
# Contributing
22

3-
Fork the repo, work on an issue
3+
This guide explains how to set up your environment, make changes, and submit a PR.
44

5-
## Updating the generated Kibana client.
5+
## Development Setup
66

7-
If your work involves the Kibana API, the endpoints may or may not be included in the generated client.
8-
Check [generated/kbapi](./generated/kbapi/) for more details.
7+
* Fork and clone the repo.
8+
* Setup your preferred IDE (Intelliji, VSCode, etc.)
99

10-
## Acceptance tests
10+
Requirements:
11+
* [Terraform](https://www.terraform.io/downloads.html) >= 1.0.0
12+
* [Go](https://golang.org/doc/install) >= 1.25
13+
* Docker (for acceptance tests)
1114

12-
```bash
13-
make docker-testacc
14-
```
15+
## Development Workflow
1516

16-
Run a single test with terraform debug enabled:
17-
```bash
18-
env TF_LOG=DEBUG make docker-testacc TESTARGS='-run ^TestAccResourceDataStreamLifecycle$$'
19-
```
17+
* Create a new branch for your changes.
18+
* Make your changes. See [Useful Commands](#useful-commands) and [Debugging](#debugging).
19+
* GitHub Copilot can be used to help with these changes (See [Using Copilot](#using-copilot))
20+
* Validate your changes
21+
* Run unit and acceptance tests (See [Running Acceptance Tests](#running-acceptance-tests)).
22+
* Run `make fmt`, `make lint`.
23+
* All checks also run automatically on every PR.
24+
* Add a changelog entry in `CHANGELOG.md` under the `Unreleased` section. This will be included in the release notes of the next release.
25+
* Submit your PR for review.
2026

21-
A way to forward debug logs to a file:
22-
```bash
23-
env TF_ACC_LOG_PATH=/tmp/tf.log TF_ACC_LOG=DEBUG TF_LOG=DEBUG make docker-testacc
24-
```
27+
When creating new resources:
28+
* Use the [Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework/getting-started/code-walkthrough) for new resources.
29+
* Use an existing resource (e.g. `internal/elasticsearch/security/system_user`) as a template.
30+
* Some resources use the deprecated Terraform SDK, so only resources using the new Terraform Framework should be used as reference.
31+
* Use the generated API clients to interact with the Kibana APIs. (See [Working with Generated API Clients](#working-with-generated-api-clients)
32+
* Add documentation and examples for the resource. Update the generated docs with `make docs-generate`.
33+
* Write unit and acceptance tests.
2534

2635

27-
## Update documentation
36+
## Using Copilot
2837

29-
Update documentation templates in `./templates` directory and re-generate docs via:
30-
```bash
31-
make docs-generate
32-
```
38+
GitHub Copilot can speed up development, but you’re responsible for correctness:
39+
* Create an issue describing the desired change and acceptance criteria.
40+
* Assign the issue to Copilot and iterate with prompts.
41+
* Review outputs carefully; add tests and adjust as needed.
42+
* Example issue: https://github.com/elastic/terraform-provider-elasticstack/issues/1219
3343

34-
## Update `./CHANGELOG.md`
44+
### Useful Commands
3545

36-
List of previous commits is a good example of what should be included in the changelog.
46+
* `make build`: Build the provider.
47+
* `make install`: Install the provider.
48+
* `make fmt`: Format the code.
49+
* `make lint`: Lint the code.
50+
* `make test`: Run unit tests.
51+
* `make docs-generate`: Generate documentation.
3752

53+
#### Running Acceptance Tests
3854

39-
## Pull request
55+
Acceptance tests spin up Elasticsearch, Kibana, and Fleet with Docker and run tests in a Go container.
4056

41-
Format the code before pushing:
57+
Quick start (default stack version from Makefile):
4258
```bash
43-
make fmt
59+
make docker-testacc
4460
```
4561

46-
Check if the linting:
62+
Run a single test with terraform debug enabled:
4763
```bash
48-
make lint
64+
env TF_LOG=DEBUG make docker-testacc TESTARGS='-run ^TestAccResourceDataStreamLifecycle$$'
4965
```
5066

51-
Create a PR and check acceptance test matrix is green.
52-
53-
## Run provider with local terraform
54-
55-
TBD
67+
A way to forward debug logs to a file:
68+
```bash
69+
env TF_ACC_LOG_PATH=/tmp/tf.log TF_ACC_LOG=DEBUG TF_LOG=DEBUG make docker-testacc
70+
```
5671

57-
## Releasing
72+
### Working with Generated API Clients
73+
74+
If your work involves the Kibana API, the API client can be generated directly from the Kibana OpenAPI specs:
75+
- For Kibana APIs, use the generated client in `generated/kbapi`.
76+
- To add new endpoints, see [generated/kbapi/README.md](generated/kbapi/README.md).
77+
- Regenerate clients with:
78+
```sh
79+
make transform generate
80+
```
81+
82+
The codebase includes a number of deprecated clients which should not be used anymore:
83+
- `libs/go-kibana-rest`: Fork of an external library, which is not maintained anymore.
84+
- `generated/alerting`
85+
- `generated/connectors`
86+
- `generated/slo`
87+
- `internal/clients/*`: Manually written clients. These should only be used/extended if it is not possible to use the generated clients.
88+
89+
### Updating Documentation
90+
91+
Docs are generated from templates in `templates/` and examples in `examples/`.
92+
* Update or add templates and examples.
93+
* Run `make docs-generate` to produce files under `docs/`.
94+
* Commit the generated files. `make lint` will fail if docs are stale.
95+
96+
### Debugging
97+
98+
Run the provider in debug mode and reattach the provider in Terraform:
99+
* Launch `main.go` with the `-debug` flag from your IDE.
100+
* After launching, the provider will print an env var. Copy the printed `TF_REATTACH_PROVIDERS='{…}'` value.
101+
* Export it in your shell where you run Terraform: `export TF_REATTACH_PROVIDERS='{…}'`.
102+
* Terraform will now talk to your debug instance, and you can set breakpoints.
103+
104+
## Project Structure
105+
106+
A quick overview over what's in each folder:
107+
108+
* `docs/` - Documentation files
109+
* `data-sources/` - Documentation for Terraform data sources
110+
* `guides/` - User guides and tutorials
111+
* `resources/` - Documentation for Terraform resources
112+
* `examples/` - Example Terraform configurations
113+
* `cloud/` - Examples using the cloud to launch testing stacks
114+
* `data-sources/` - Data source usage examples
115+
* `resources/` - Resource usage examples
116+
* `provider/` - Provider configuration examples
117+
* `generated/` - Auto-generated clients from the `generate-clients` make target
118+
* `kbapi/` - Kibana API client
119+
* `alerting/` - (Deprecated) Kibana alerting API client
120+
* `connectors/` - (Deprecated) Kibana connectors API client
121+
* `slo/` - (Deprecated) SLO (Service Level Objective) API client
122+
* `internal/` - Internal Go packages
123+
* `acctest/` - Acceptance test utilities
124+
* `clients/` - API client implementations
125+
* `elasticsearch/` - Elasticsearch-specific logic
126+
* `fleet/` - Fleet management functionality
127+
* `kibana/` - Kibana-specific logic
128+
* `models/` - Data models and structures
129+
* `schema/` - Connection schema definitions for plugin framework
130+
* `utils/` - Utility functions
131+
* `versionutils/` - Version handling utilities
132+
* `libs/` - External libraries
133+
* `go-kibana-rest/` - (Deprecated) Kibana REST API client library
134+
* `provider/` - Core Terraform provider implementation
135+
* `scripts/` - Utility scripts for development and CI
136+
* `templates/` - Template files for documentation generation
137+
* `data-sources/` - Data source documentation templates
138+
* `resources/` - Resource documentation templates
139+
* `guides/` - Guide documentation templates
140+
* `xpprovider/` - Additional provider functionality needed for Crossplane
141+
142+
## Releasing (maintainers)
58143

59144
Releasing is implemented in CI pipeline.
60145

@@ -65,4 +150,4 @@ To release a new provider version:
65150
- updates CHANGELOG.md with the list of changes being released.
66151
[Example](https://github.com/elastic/terraform-provider-elasticstack/commit/be866ebc918184e843dc1dd2f6e2e1b963da386d).
67152

68-
* Once the PR is merged, the release CI pipeline can be started by pushing a new release tag to the `main` branch.
153+
* Once the PR is merged, the release CI pipeline can be started by pushing a new release tag to the `main` branch. (`git tag v0.11.13 && git push origin v0.11.13`)

‎README.md‎

Lines changed: 2 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -76,71 +76,10 @@ provider "elasticstack" {
7676
}
7777
```
7878

79-
8079
## Developing the Provider
8180

82-
If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements)).
83-
84-
To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
85-
86-
To install the provider locally into the `~/.terraform.d/plugins/...` directory one can use `make install` command. This will allow to refer this provider directly in the Terraform configuration without needing to download it from the registry.
87-
88-
To generate or update documentation, run `make gen`. All the generated docs will have to be committed to the repository as well.
89-
90-
In order to run the full suite of Acceptance tests, run `make testacc`.
91-
92-
If you have [Docker](https://docs.docker.com/get-docker/) installed, you can use following command to start the Elasticsearch container and run Acceptance tests against it:
93-
94-
```sh
95-
$ make docker-testacc
96-
```
97-
98-
To clean up the used containers and to free up the assigned container names, run `make docker-clean`.
99-
100-
Note: there have been some issues encountered when using `tfenv` for local development. It's recommended you move your version management for terraform to `asdf` instead.
101-
102-
103-
### Requirements
104-
105-
- [Terraform](https://www.terraform.io/downloads.html) >= 1.0.0
106-
- [Go](https://golang.org/doc/install) >= 1.19
107-
108-
109-
### Building The Provider
110-
111-
1. Clone the repository
112-
1. Enter the repository directory
113-
1. Build the provider using the `make install` command:
114-
```sh
115-
$ make install
116-
```
117-
118-
119-
### Adding Dependencies
120-
121-
This provider uses [Go modules](https://github.com/golang/go/wiki/Modules).
122-
Please see the Go documentation for the most up to date information about using Go modules.
123-
124-
To add a new dependency `github.com/author/dependency` to your Terraform provider:
125-
126-
```
127-
go get github.com/author/dependency
128-
go mod tidy
129-
```
130-
131-
Then commit the changes to `go.mod` and `go.sum`.
132-
133-
### Generating Kibana clients
134-
135-
Kibana clients for some APIs are generated based on Kibana OpenAPI specs.
136-
Please see [Makefile](./Makefile) tasks for more details.
137-
138-
## Support
139-
140-
We welcome questions on how to use the Elastic providers. The providers are supported by Elastic. General questions, bugs and product issues should be raised in their corresponding repositories, either for the Elastic Stack provider, or the Elastic Cloud one. Questions can also be directed to the discuss forum. https://discuss.elastic.co/c/orchestration.
141-
142-
We will not, however, fix bugs upon customer demand, as we have to prioritize all pending bugs and features, as part of the product's backlog and release cycles.
81+
See [CONTRIBUTING.md](CONTRIBUTING.md)
14382

144-
### Support tickets severity
83+
## Support tickets severity
14584

14685
Support tickets related to the Terraform provider can be opened with Elastic, however since the provider is just a client of the underlying product API's, we will not be able to treat provider related support requests as a Severity-1 (Immedediate time frame). Urgent, production-related Terraform issues can be resolved via direct interaction with the underlying project API or UI. We will ask customers to resort to these methods to resolve downtime or urgent issues.

0 commit comments

Comments
 (0)