From 34763746d67d482fee8129cc1605d3953c91a4cb Mon Sep 17 00:00:00 2001
From: Timo Furrer <tfurrer@gitlab.com>
Date: Tue, 6 Feb 2024 07:00:17 +0100
Subject: [PATCH] Improve README

---
 .gitlab/README.md.template | 38 +++++++++++++++++++++++++++++++++-----
 README.md                  | 38 +++++++++++++++++++++++++++++++++-----
 2 files changed, 66 insertions(+), 10 deletions(-)

diff --git a/.gitlab/README.md.template b/.gitlab/README.md.template
index c41963f..5306016 100644
--- a/.gitlab/README.md.template
+++ b/.gitlab/README.md.template
@@ -1,14 +1,12 @@
 # OpenTofu CI/CD Component
 
-> 🚨 🚧 **NOTE** 🚧 🚨 
+> 🚧 **NOTE** 🚧
 > 
-> This component is **work in progress**, where inputs, template names and the entire interface in general may 
-> change at any time until version 1.0.0 is reached. From where on this CI/CD component will be versioned using [semver 2.0](https://semver.org/).
-> The progress of implementing such a version can be tracked in https://gitlab.com/groups/gitlab-org/-/epics/12401.
->
 > The `src/gitlab-tofu.sh` script is still merely a copy from [`gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images).
 > Therefore, lots of things in this script and in the templates are still Terraform-related and haven't
 > been changed to their OpenTofu equivalents.
+> Have a look at the [Migrating from the Terraform CI/CD templates](#migrating-from-the-terraform-cicd-templates) 
+section when migrating from Terraform CI/CD templates.
 
 This project is home to the **OpenTofu CI/CD component** and it's related assets, 
 like the `gitlab-tofu` wrapper script and OCI images containing that script
@@ -40,6 +38,20 @@ include:
       opentofu_version: <OPENTOFU_VERSION>
 
 stages: [validate, build, deploy, cleanup]
+
+---
+
+# ... or without the destroy jobs:
+include:
+  - component: gitlab.com/components/opentofu/validate-plan-apply@<VERSION>
+    inputs:
+      # The version must currently be specified explicitly as an input,
+      # to find the correctly associated images. # This can be removed
+      # once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
+      version: <VERSION>
+      opentofu_version: <OPENTOFU_VERSION>
+
+stages: [validate, build, deploy]
 ```
 
 A concrete example may look like this:
@@ -162,6 +174,14 @@ Have a look at the individual template spec to learn about the available inputs.
 | ---- | ------- | ----------- |
 <INPUTS>
 
+### Variables
+
+(🚧 *This section is work in progress*)
+
+Have a look at the [`src/gitlab-tofu.sh`](src/gitlab-tofu.sh) script and how the `TF_`-prefixed
+variables are being used. You may set them according to your needs.
+
+
 ## Releases & Versioning
 
 This project currently releases tagged commits. 
@@ -235,10 +255,18 @@ When migrating from the GitLab Terraform CI/CD templates you can use the followi
 - Migrate the `TF_STATE_NAME` variable to the `state_name` input.
     - Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
 - Migrate the `TF_AUTO_DEPLOY` variable to the `auto_apply` input.
+- Used other variables -> Use the same variables with this component.
 
 The same rules apply for the `latest` templates.
 We also recommend to check out the [Usage](#Usage) section for more details about the available templates and inputs.
 
+### OpenTofu component `inputs` vs. Terraform template `variables`
+
+This OpenTofu CI/CD component makes use of [`inputs`](https://docs.gitlab.com/ee/ci/yaml/#specinputs)
+whereas the Terraform CI/CD templates used [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables).
+We recommend that you use the `inputs` with the OpenTofu component where available and required.
+However, if needed you may overwrite the jobs and set the `variables` you like.
+
 ## Contributing
 
 See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
diff --git a/README.md b/README.md
index 876ae94..7fdec3e 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,13 @@
 
 # OpenTofu CI/CD Component
 
-> 🚨 🚧 **NOTE** 🚧 🚨 
+> 🚧 **NOTE** 🚧
 > 
-> This component is **work in progress**, where inputs, template names and the entire interface in general may 
-> change at any time until version 1.0.0 is reached. From where on this CI/CD component will be versioned using [semver 2.0](https://semver.org/).
-> The progress of implementing such a version can be tracked in https://gitlab.com/groups/gitlab-org/-/epics/12401.
->
 > The `src/gitlab-tofu.sh` script is still merely a copy from [`gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images).
 > Therefore, lots of things in this script and in the templates are still Terraform-related and haven't
 > been changed to their OpenTofu equivalents.
+> Have a look at the [Migrating from the Terraform CI/CD templates](#migrating-from-the-terraform-cicd-templates) 
+section when migrating from Terraform CI/CD templates.
 
 This project is home to the **OpenTofu CI/CD component** and it's related assets, 
 like the `gitlab-tofu` wrapper script and OCI images containing that script
@@ -42,6 +40,20 @@ include:
       opentofu_version: <OPENTOFU_VERSION>
 
 stages: [validate, build, deploy, cleanup]
+
+---
+
+# ... or without the destroy jobs:
+include:
+  - component: gitlab.com/components/opentofu/validate-plan-apply@<VERSION>
+    inputs:
+      # The version must currently be specified explicitly as an input,
+      # to find the correctly associated images. # This can be removed
+      # once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
+      version: <VERSION>
+      opentofu_version: <OPENTOFU_VERSION>
+
+stages: [validate, build, deploy]
 ```
 
 A concrete example may look like this:
@@ -181,6 +193,14 @@ The following OpenTofu versions are available with this component via the `opent
 - [`1.6.0`](https://github.com/opentofu/opentofu/releases/tag/v1.6.0)
 - [`1.6.0-rc1`](https://github.com/opentofu/opentofu/releases/tag/v1.6.0-rc1)
 
+### Variables
+
+(🚧 *This section is work in progress*)
+
+Have a look at the [`src/gitlab-tofu.sh`](src/gitlab-tofu.sh) script and how the `TF_`-prefixed
+variables are being used. You may set them according to your needs.
+
+
 ## Releases & Versioning
 
 This project currently releases tagged commits. 
@@ -254,10 +274,18 @@ When migrating from the GitLab Terraform CI/CD templates you can use the followi
 - Migrate the `TF_STATE_NAME` variable to the `state_name` input.
     - Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
 - Migrate the `TF_AUTO_DEPLOY` variable to the `auto_apply` input.
+- Used other variables -> Use the same variables with this component.
 
 The same rules apply for the `latest` templates.
 We also recommend to check out the [Usage](#Usage) section for more details about the available templates and inputs.
 
+### OpenTofu component `inputs` vs. Terraform template `variables`
+
+This OpenTofu CI/CD component makes use of [`inputs`](https://docs.gitlab.com/ee/ci/yaml/#specinputs)
+whereas the Terraform CI/CD templates used [`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables).
+We recommend that you use the `inputs` with the OpenTofu component where available and required.
+However, if needed you may overwrite the jobs and set the `variables` you like.
+
 ## Contributing
 
 See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.
-- 
GitLab