Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
154 lines (103 loc) · 7.97 KB

CONTRIBUTING.md

File metadata and controls

154 lines (103 loc) · 7.97 KB

Contributing

Contributions are welcome!

Contributors Last commit Stars

New Contributor Guide

If you are a new contributor this section aims to show you everything you need to get started.

We especially welcome contributions to issues that are labeled with "good-first-issue" or "help-wanted".

We also encourage contributions in the form of:

  • bug/crash reports
  • Answering questions on Slack
  • Posting your use-case for the provider on Slack / Blog Post

Setting up

To contribute to this Provider you need the following tools installed locally:

Codespaces

If you don't want to install tools locally you can use Github Codespaces to contribute to this project. We have a pre-configured codespace that should have all tools installed already:

Open in GitHub Codespaces

Contributing checklist

Please keep in mind the following guidelines and practices when contributing to the Provider:

  1. Your commit must be signed (git commit --signoff). We use the DCO application that enforces the Developer Certificate of Origin (DCO) on commits.
  2. Use make fmt to format the repository code.
  3. Use make lint to lint the project.
  4. Use make generate to generate documentation on schema changes
  5. Add unit tests for any new code you write.
  6. Add an example, or extend an existing example in the examples, with any new features you may add. Use make generate to add examples to the docs

Building

  1. git clone this repository and cd into its directory
  2. make build will trigger the Golang build and place it's binary in <git-repo-path>/bin/terraform-provider-argocd

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 containerized-K3s cluster. We are using testcontainers for this. If you have a supported container runtime installed you can simply run the tests using:

make testacc # to run all the Terraform tests
make test # to only run helper unit tests (minority of the testcases)

Documentation

This provider uses 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.

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

Debugging

We have some pre-made config to debug and run the provider using VSCode. If you are using another IDE take a look at Hashicorp's Debug docs for instructions or adapt .vscode/launch.json for your IDE

Running the Terraform provider in debug mode (VSCode-specific)

To use the preconfigured debug config in VS Code open the Debug tab and select the profile "Debug Terraform Provider". Set some breakpoints and then run this task.

Head to the debug console and copy the line where it says TF_REATTACH_PROVIDERS to the clipboard.

Open a terminal session and export the TF_REATTACH_PROVIDERS variable in this session. Every Terraform CLI command in this terminal session will then ensure it's using the provider already running inside VS Code and attach to it.

Example of such a command:

export TF_REATTACH_PROVIDERS='{"registry.terraform.io/argoproj-labs/argocd":{"Protocol":"grpc","ProtocolVersion":6,"Pid":2065,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/rj/_02y2jmn3k1bxx45wlzt2dkc0000gn/T/plugin193859953"}}}' 
terraform apply -auto-approve # will use the provider running in debug-mode

Note: if the provider crashes or you restart the debug-session you have to re-export this variable to your terminal for the Terraform CLI to find the already running provider!

Running acceptance tests in debug mode (VSCode-specific)

Open a test file, hover over a test function's name and then in the Debug tab of VSCode select "Debug selected Test". This will run the test you selected with the specific arguments required for Terraform to run the acceptance test.

Note: You shouldn't use the builtin "Debug Test" profile that is shown when hovering over a test function since it doesn't contain the necessary configuration to find your Argo CD environment.

Run Terraform using a local build

It's possible to set up a local terraform configuration to use a development build of the provider. This can be achieved by leveraging the Terraform CLI configuration file development overrides.

First, use make install to place a fresh development build of the provider in your ${GOBIN} (defaults to ${GOPATH}/bin or ${HOME}/go/bin if ${GOPATH} is not set). Repeat this every time you make changes to the provider locally.

Note: you can also use make build to place the binary into <git-repo-path>/bin/terraform-provider-argocd instead.

Then write this config to a file:

provider_installation {
  dev_overrides {
    "argoproj-labs/argocd" = "/Users/username/go/bin" # path must be absolute and point to the directoy containing the binary
  }

  direct {}
}

And lastly use the following environment variable in a terminal session to tell Terraform to use this file for picking up the development binary:

export TF_CLI_CONFIG_FILE=../.reproduce/.terraformrc
terraform plan # will not use the local provider build

For further reference consult HashiCorp's article about this topic.

Dependency Management

K8s version

In our CI we test against a Kubernetes version that is supported by all Argo CD versions we support.

That version can be obtained when looking at this table in the Argo CD documentation.

Argo CD client-lib

Some dependencies we use are strictly aligned with the Argo CD client-lib that we use and should only be updated together:

  • github.com/argoproj/gitops-engine
  • k8s.io/*

Please don't update any of these dependencies without having discussed this first!