Skip to content

Commit ea92323

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

File tree

2 files changed

+122
-92
lines changed

2 files changed

+122
-92
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: 1 addition & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -76,64 +76,9 @@ 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.
81+
See [CONTRIBUTING.md](CONTRIBUTING.md)
13782

13883
## Support
13984

0 commit comments

Comments
 (0)