Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Move Contributing docs to separate file #420

Merged
merged 2 commits into from
Oct 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Contributing

Contributions are welcome!

## Building

1. `git clone` this repository and `cd` into its directory
2. `make build` will trigger the Golang build

The provided `GNUmakefile` defines additional commands generally useful during
development, like for running tests, generating documentation, code formatting
and linting. Taking a look at its content is recommended.

## Testing

The acceptance tests run against a disposable ArgoCD installation within a
[Kind](https://github.com/kubernetes-sigs/kind) cluster. Other requirements are
having a Docker daemon running and
[Kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/)
installed.

```sh
make testacc_prepare_env
make testacc
make testacc_clean_env
```

## Generating documentation

This provider uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/)
to generate documentation and store it in the `docs/` directory.
Once a release is cut, the Terraform Registry will download the documentation from `docs/`
and associate it with the release version. Read more about how this works on the
[official page](https://www.terraform.io/registry/providers/docs).

Use `make generate` to ensure the documentation is regenerated with any changes.

## Using a development build

If [running tests and acceptance tests](#testing) isn't enough, it's possible to
set up a local terraform configuration to use a development builds of the
provider. This can be achieved by leveraging the Terraform CLI [configuration
file development
overrides](https://www.terraform.io/cli/config/config-file#development-overrides-for-provider-developers).

First, use `make install` to place a fresh development build of the provider in
your
[`${GOBIN}`](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
(defaults to `${GOPATH}/bin` or `${HOME}/go/bin` if `${GOPATH}` is not set).
Repeat this every time you make changes to the provider locally.

Then, setup your environment following [these
instructions](https://www.terraform.io/plugin/debugging#terraform-cli-development-overrides)
to make your local terraform use your local build.

## Troubleshooting during local development

* **"too many open files":** Running all acceptance tests in parallel (the
default) may open a lot of files and sockets, therefore ensure your local
workstation [open files/sockets limits are tuned
accordingly](https://k6.io/docs/misc/fine-tuning-os).
63 changes: 0 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,69 +74,6 @@ in the process.
* [Go](https://go.dev/doc/install) (1.19)
* [GNU Make](https://www.gnu.org/software/make/)
* [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) (optional)


## Contributing

Contributions are welcome!

### Building

1. `git clone` this repository and `cd` into its directory
2. `make build` will trigger the Golang build

The provided `GNUmakefile` defines additional commands generally useful during
development, like for running tests, generating documentation, code formatting
and linting. Taking a look at it's content is recommended.

### Testing

The acceptance tests run against a disposable ArgoCD installation within a
[Kind](https://github.com/kubernetes-sigs/kind) cluster. Other requirements are
having a Docker daemon running and
[Kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/)
installed.

```sh
make testacc_prepare_env
make testacc
make testacc_clean_env
```

### Generating documentation

This provider uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/)
to generate documentation and store it in the `docs/` directory.
Once a release is cut, the Terraform Registry will download the documentation from `docs/`
and associate it with the release version. Read more about how this works on the
[official page](https://www.terraform.io/registry/providers/docs).

Use `make generate` to ensure the documentation is regenerated with any changes.

### Using a development build

If [running tests and acceptance tests](#testing) isn't enough, it's possible to
set up a local terraform configuration to use a development builds of the
provider. This can be achieved by leveraging the Terraform CLI [configuration
file development
overrides](https://www.terraform.io/cli/config/config-file#development-overrides-for-provider-developers).

First, use `make install` to place a fresh development build of the provider in
your
[`${GOBIN}`](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
(defaults to `${GOPATH}/bin` or `${HOME}/go/bin` if `${GOPATH}` is not set).
Repeat this every time you make changes to the provider locally.

Then, setup your environment following [these
instructions](https://www.terraform.io/plugin/debugging#terraform-cli-development-overrides)
to make your local terraform use your local build.

### Troubleshooting during local development

* **"too many open files":** Running all acceptance tests in parallel (the
default) may open a lot of files and sockets, therefore ensure your local
workstation [open files/sockets limits are tuned
accordingly](https://k6.io/docs/misc/fine-tuning-os).

---

Expand Down
Loading