diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md index 6dea5903..e11c1999 100644 --- a/CONTRIBUTION.md +++ b/CONTRIBUTION.md @@ -1,7 +1,30 @@ -## Contribute -Your contribution is welcome! Please create a pull request (PR). The STACKIT Developer Tools team will review it. A more detailed contribution guideline is planned to come. +# Contribute to the STACKIT Terraform Provider +Your contribution is welcome! Thank you for your interest in contributing to the STACKIT Terraform Provider. We greatly value your feedback, feature requests, additions to the code, bug reports or documentation extensions. -### Local development +## Table of contents +- [Developer Guide](#developer-guide) +- [Code Contributions](#code-contributions) +- [Bug Reports](#bug-reports) + +## Developer Guide +### Repository structure +The provider resources and data sources for the STACKIT services are located under `stackit/services`. Inside `stackit` you can find several other useful packages such as `validate` and `testutil`. Examples of usage of the provider are located under the `examples` folder. + +### Getting started + +Check the [Authentication](README.md#authentication) section on the README. + +#### Useful Make commands + +These commands can be executed from the project root: + +- `make project-tools`: get the required dependencies +- `make lint`: lint the code and examples +- `make generate-docs`: generate terraform documentation +- `make test`: run unit tests +- `make test-acceptance-tf`: run acceptance tests + +#### Local development To test your changes locally, you have to compile the provider (requires Go 1.20) and configure the Terraform CLI to use the local version. @@ -37,7 +60,7 @@ terraform { 6. Setup authentication by setting the env var `STACKIT_SERVICE_ACCOUNT_TOKEN` as a valid token (see [Authentication](#authentication) for more details on how to autenticate). 7. Run `terraform plan` or `terraform apply` commands. -# Setup centralized Terraform state +#### Setup centralized Terraform state You'll need a storage bucket to store the Terraform state and a pair of access key/secret key. - To order the bucket in the STACKIT Portal, go to Object Storage (on the right) > Buckets > Create bucket. @@ -48,4 +71,24 @@ In the main.tf file location, initialize Terraform by running the following: terraform init -reconfigure -upgrade -backend-config="access_key=" -backend-config="secret_key=" ``` -This will throw an error ("Failed to query available provider packages") which can be ignored since we are using the local provider build. \ No newline at end of file +This will throw an error ("Failed to query available provider packages") which can be ignored since we are using the local provider build. + +## Code Contributions + +To make your contribution, follow these steps: +1. Check open or recently closed [Pull Requests](https://github.com/stackitcloud/terraform-provider-stackit/pulls) and [Issues](https://github.com/stackitcloud/terraform-provider-stackit/issues)to make sure the contribution you are making has not been already tackled by someone else. +2. Fork the repo. +3. Make your changes in a branch that is up-to-date with the original repo's `main` branch. +4. Commit your changes including a descriptive message +5. Create a pull request with your changes. +6. The pull request will be reviewed by the repo maintainers. If you need to make further changes, make additional commits to keep commit history. When the PR is merged, commits will be squashed. + +## Bug Reports +If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/terraform-provider-stackit/issues/new). + +To ensure we can provide the best support to your issue, follow these guidelines: + +1. Go through the existing issues to check if your issue has already been reported. +2. Make sure you are using the latest version of the provider, we will not provide bug fixes for older versions. Also, latest versions may have the fix for your bug. +3. Please provide as much information as you can about your environment, e.g. your version of Go, your version of the provider, which operating system you are using and the corresponding version. +4. Include in your issue the steps to reproduce it, along with code snippets and/or information about your specific use case. This will make the support process much easier and efficient.