docs: add explanation about our dependency management + clarify version compatiblity in README (#607)

* chore(docs): add docs about version compatiblity/dependencies

Signed-off-by: Nathanael Liechti <[email protected]>

* chore: appliy @onematchfox's version of the table

Co-authored-by: Brian Fox <[email protected]>
Signed-off-by: Nathanael Liechti <[email protected]>

---------

Signed-off-by: Nathanael Liechti <[email protected]>
Co-authored-by: Brian Fox <[email protected]>

Author: the-technat

CONTRIBUTING.md

@@ -2,6 +2,21 @@
 
 Contributions are welcome! 
 
+## 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](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/#tested-versions) 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!
+
 ## Building
 
 1. `git clone` this repository and `cd` into its directory

README.md

@@ -29,6 +29,52 @@ Official documentation on how to use this provider can be found on the
 [Terraform
 Registry](https://registry.terraform.io/providers/argoproj-labs/argocd/latest/docs).
 
+## Version Compatibility 
+
+The provider supports all versions Argo-CD itself currently supports. See the [Argo CD documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/#supported-versions) for supported versions.
+
+The following table shows the versions of Argo CD that are tested with each version of the provider.
+
+| Provider version | Argo CD versions |
+|---|---|
+| 7.5 | v2.12, v2.13, v2.14 | 
+| 7.4 | v2.11, v2.12, v2.13 | 
+| 7.2 | v2.10, v2.11, v2.12 | 
+| 7.1 | v2.9, v2.10, v2.11 | 
+| 7.0 | v2.8, v2.9, v2.10 | 
+| 6.x | v2.8, v2.9, v2.10 | 
+
+Note: these numbers are based on our testing matrix that tests the provider against these versions of Argo CD. You may be able to use other provider versions as the ones listed here and it may still work.
+
+## Motivations
+
+### *I thought ArgoCD already allowed for 100% declarative configuration?*
+
+While that is true through the use of ArgoCD Kubernetes Custom Resources, there
+are some resources that simply cannot be managed using Kubernetes manifests,
+such as project roles JWTs whose respective lifecycles are better handled by a
+tool like Terraform. Even more so when you need to export these JWTs to another
+external system using Terraform, like a CI platform.
+
+### *Wouldn't using a Kubernetes provider to handle ArgoCD configuration be enough?*
+
+Existing Kubernetes providers do not patch arrays of objects, losing project
+role JWTs when doing small project changes just happen.
+
+ArgoCD Kubernetes admission webhook controller is not as exhaustive as ArgoCD
+API validation, this can be seen with RBAC policies, where no validation occur
+when creating/patching a project.
+
+Using Terraform to manage Kubernetes Custom Resource becomes increasingly
+difficult the further you use HCL2 DSL to merge different data structures *and*
+want to preserve type safety.
+
+Whatever the Kubernetes CRD provider you are using, you will probably end up
+using `locals` and the `yamlencode` function **which does not preserve the
+values' type**. In these cases, not only the readability of your Terraform plan
+will worsen, but you will also be losing some safeties that Terraform provides
+in the process.
+
 ## Upgrading
 
 ### Migrate provider source `oboukili` -> `argoproj-labs`
@@ -121,47 +167,10 @@ HashiCorps [replace-provider] docs. In summary, you can do the following:
 
 5. You have successfully migrated
 
-## Compatibility promise
-
-This provider is compatible with _at least_ the last 2 minor releases of ArgoCD
-(e.g, ranging from 1.(n).m, to 1.(n-1).0, where `n` is the latest available
-minor version).
-
-Older releases are not supported and some resources may not work as expected.
-
-## Motivations
-
-### *I thought ArgoCD already allowed for 100% declarative configuration?*
-
-While that is true through the use of ArgoCD Kubernetes Custom Resources, there
-are some resources that simply cannot be managed using Kubernetes manifests,
-such as project roles JWTs whose respective lifecycles are better handled by a
-tool like Terraform. Even more so when you need to export these JWTs to another
-external system using Terraform, like a CI platform.
-
-### *Wouldn't using a Kubernetes provider to handle ArgoCD configuration be enough?*
-
-Existing Kubernetes providers do not patch arrays of objects, losing project
-role JWTs when doing small project changes just happen.
-
-ArgoCD Kubernetes admission webhook controller is not as exhaustive as ArgoCD
-API validation, this can be seen with RBAC policies, where no validation occur
-when creating/patching a project.
-
-Using Terraform to manage Kubernetes Custom Resource becomes increasingly
-difficult the further you use HCL2 DSL to merge different data structures *and*
-want to preserve type safety.
-
-Whatever the Kubernetes CRD provider you are using, you will probably end up
-using `locals` and the `yamlencode` function **which does not preserve the
-values' type**. In these cases, not only the readability of your Terraform plan
-will worsen, but you will also be losing some safeties that Terraform provides
-in the process.
-
 ## Requirements
 
 * [Terraform](https://www.terraform.io/downloads) (>= 1.0)
-* [Go](https://go.dev/doc/install) (1.19)
+* [Go](https://go.dev/doc/install) (1.24)
 * [GNU Make](https://www.gnu.org/software/make/)
 * [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) (optional)