feat(docs): improve contribution docs (#1008)

relates to STACKITTPR-317

Author: marceljk

CONTRIBUTION.md

@@ -93,12 +93,13 @@ https://github.com/stackitcloud/terraform-provider-stackit/blob/1b9225598a007cda
 To test your changes locally, you have to compile the provider (requires Go 1.24) and configure the Terraform CLI to use the local version.
 
 1. Clone the repository.
+1. Run `$ make build` to build the Terraform provider binary in `<PATH_TO_REPO>/bin/`
 1. Create a `.terraformrc` config file in your home directory (`~`) for the terraform CLI with the following content:
 
 	```hcl
 	provider_installation {
    	   dev_overrides {
-	      "registry.terraform.io/stackitcloud/stackit" = "<PATH_TO_BINARY>"
+	      "registry.terraform.io/stackitcloud/stackit" = "<PATH_TO_REPO>/bin/"
 	   }
 
 	   # For all other providers, install them directly from their origin provider
@@ -163,6 +164,16 @@ To make your contribution, follow these steps:
 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.
 
+> [!TIP]
+> 
+> To ensure smooth review and integration of your code contributions, follow these guidelines:
+>
+> **Break down large changes into smaller PRs**: Separate new features or bigger changes into multiple smaller Pull Requests.
+> This allows us to provide earlier feedback and makes it easier to review your PR.
+> 
+> **Create a draft PR for early feedback**: If you want feedback during the implementation process, create a draft PR so we can have a look. 
+
+
 ## Bug Reports
 
 If you would like to report a bug, please open a [GitHub issue](https://github.com/stackitcloud/terraform-provider-stackit/issues/new).

Makefile

@@ -46,12 +46,14 @@ coverage:
 test-acceptance-tf:
 	@if [ -z $(TF_ACC_PROJECT_ID) ]; then echo "Input TF_ACC_PROJECT_ID missing"; exit 1; fi
 	@if [ -z $(TF_ACC_ORGANIZATION_ID) ]; then echo "Input TF_ACC_ORGANIZATION_ID missing"; exit 1; fi
+	@if [ -z $(TF_ACC_REGION) ]; then echo "Input TF_ACC_REGION missing"; exit 1; fi
 	@if [ -z $(TF_ACC_TEST_IMAGE_LOCAL_FILE_PATH) ]; then \
 		echo "Input TF_ACC_TEST_IMAGE_LOCAL_FILE_PATH missing. Creating a default file for testing."; \
 	fi
 	@echo "Running acceptance tests for the terraform provider"
 	@cd $(ROOT_DIR)/stackit && TF_ACC=1 \
 	TF_ACC_PROJECT_ID=$(TF_ACC_PROJECT_ID) \
 	TF_ACC_ORGANIZATION_ID=$(TF_ACC_ORGANIZATION_ID) \
+	TF_ACC_REGION=$(TF_ACC_REGION) \
 	go test ./... -count=1 -timeout=30m && \
 	cd $(ROOT_DIR)

README.md

@@ -207,22 +207,68 @@ If you don't need these fields, don't set the experiment flag `network`, to use
 
 ## Acceptance Tests
 
+> [!WARNING]
+> Acceptance tests will create real resources, which may incur in costs.
+> Some resource may leftover after a test run. This could happen if the tests are modified, tests are stopped during the run or losing the network connection.
+> These resource must be removed manually with the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli) or the STACKIT Portal.
+
 Terraform acceptance tests are run using the command `make test-acceptance-tf`. For all services,
 
 - The env var `TF_ACC_PROJECT_ID` must be set with the ID of the STACKIT test project to test it.
+- The env var `TF_ACC_REGION` must be set with the region in which the tests should be run.
 - Authentication is set as usual.
 - Optionally, the env var `TF_ACC_XXXXXX_CUSTOM_ENDPOINT` (where `XXXXXX` is the uppercase name of the service) can be set to use endpoints other than the default value.
 - There are some acceptance test where it is needed to provide additional parameters, some of them have default values in order to run normally without manual interaction. Those default values can be overwritten (see testutils.go for a full list.)
 
 Additionally:
 
-- For the Resource Manager service:
-  - A service account with permissions to create and delete projects is required
-  - The env var `TF_ACC_TEST_PROJECT_SERVICE_ACCOUNT_EMAIL` must be set as the email of the service account
-  - The env var `TF_ACC_TEST_PROJECT_SERVICE_ACCOUNT_TOKEN` must be set as a valid token of the service account. Can also be set in the credentials file used by authentication (see [Authentication](#authentication) for more details)
-  - The env var `TF_ACC_PROJECT_ID` is ignored
+| Env var                                     | Value                                                                                                   | Example value                          | needed for Acc tests of the following services |
+|---------------------------------------------|---------------------------------------------------------------------------------------------------------|----------------------------------------|------------------------------------------------|
+| `TF_ACC_ORGANIZATION_ID`                    | ID of the STACKIT test organization                                                                     | `5353ccfa-a984-4b96-a71d-b863dd2b7087` | `authorization`, `iaas`                        |
+| `TF_ACC_TEST_PROJECT_SERVICE_ACCOUNT_EMAIL` | Email of the STACKIT service account                                                                    | `[email protected]`  | `authorization`, `resourcemanager`             |
+| `TF_ACC_SERVER_ID`                          | ID of a STACKIT Server with STACKIT Server Agent enabled                                                | `5353ccfa-a984-4b96-a71d-b863dd2b7087` | `serverbackup`, `serverupdate`                 |
+| `TF_ACC_TEST_PROJECT_PARENT_CONTAINER_ID`   | Container ID of the project parent container (folder within an organization or the organization itself) | `organization-d2b7087`                 | `resourcemanager`                              |
+| `TF_ACC_TEST_PROJECT_PARENT_UUID`           | UUID ID of the project parent container (folder within an organization or the organization itself)      | `5353ccfa-a984-4b96-a71d-b863dd2b7087` | `resourcemanager`                              |
+
+### Run Acceptance Tests of a single service
+
+> [!WARNING]
+> Acceptance tests will create real resources, which may incur in costs.
+> Some resource may leftover after a test run. This could happen if the tests are modified, tests are stopped during the run or losing the network connection.
+> These resource must be removed manually with the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli) or the STACKIT Portal.
+
+For running the acceptance tests of a single service, set the required env vars from above.
+Set the env var `TF_ACC=1`, to enable the acceptance tests. 
+
+Start the acceptance tests:
+
+1. Configure your env vars in a file, e.g.
+   ```sh
+   # acc-tests.env
+   export TF_ACC="1"
+   export TF_ACC_REGION="eu01"
+   ...
+   ```
+2. Read the env vars from the file
+   ```sh
+   source acc-tests.env
+   ```
+3. Start the acceptance tests
+    ```sh
+    $ go test -timeout=60m -v stackit/internal/services/<service>/<service>_acc_test.go
+    ```
+
+Alternative, set your env vars inline and start the acceptance test:
+```sh
+$ TF_ACC=1 \
+  TF_ACC_PROJECT_ID=<PROJECT_ID> \
+  TF_ACC_REGION=<REGION> \
+  STACKIT_SERVICE_ACCOUNT_KEY_PATH=<PATH/TO/SA_KEY.json> \
+  go test -timeout=60m -v stackit/internal/services/<service>/<service>_acc_test.go
+```
+
 
-**WARNING:** Acceptance tests will create real resources, which may incur in costs.
+For some services the acceptance tests take more time. By setting the timeout via the flag `-timeout=` to a higher time, you ensure that the tests will not be stopped.
 
 ## Migration
 

stackit/internal/services/ske/ske_acc_test.go

@@ -53,7 +53,6 @@ var testConfigVarsMin = config.Variables{
 
 var testConfigVarsMax = config.Variables{
 	"project_id":                                       config.StringVariable(testutil.ProjectId),
-	"organization_id":                                  config.StringVariable(testutil.OrganizationId),
 	"name":                                             config.StringVariable(maxTestName),
 	"nodepool_availability_zone1":                      config.StringVariable(fmt.Sprintf("%s-1", testutil.Region)),
 	"nodepool_machine_type":                            config.StringVariable("g2i.2"),