Clarify CAPI vs conformance

Author: fabriziopandini

CONTRIBUTING.md

@@ -75,10 +75,8 @@ Cluster API follows upstream Kubernetes semantic versioning. With the v1 release
 
 - A (*patch*) release SHOULD only include backwards compatible set of bugfixes.
 
-These guarantees extend to all code exposed in our Go Module, including
-*types from dependencies in public APIs*.
-Types and functions not in public APIs are not considered part of the guarantee.
-The test module, clusterctl, and experiments do not provide any backward compatible guarantees.
+see [Cluster API release support](https://cluster-api.sigs.k8s.io/reference/versions.html#cluster-api-release-support)) for
+more details about supported releases and for considerations that might apply if you are importing Cluster API go modules as a dependency.
 
 #### Backporting a patch
 

docs/book/src/developer/providers/contracts/bootstrap-config.md

@@ -1,6 +1,6 @@
 # Contract rules for BootstrapConfig
 
-Bootstrap providers SHOULD implement a BootstrapConfig resource.
+Bootstrap providers SHOULD implement a BootstrapConfig resource using Kubernetes' CustomResourceDefinition (CRD).
 
 The goal of a BootstrapConfig resource is to generates bootstrap data that is used to bootstrap a Kubernetes node.
 These may be e.g. [cloud-init] scripts.
@@ -501,6 +501,6 @@ The following diagram shows the typical logic for a bootstrap provider:
 [clusterctl provider contract]: clusterctl.md
 [implementation best practices]: ../best-practices.md
 [Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
-[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate_webhook.go
+[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate.go
 [BootstrapConfig: pausing]: #bootstrapconfig-pausing
 [Cluster API v1.11 migration notes]: ../migrations/v1.10-to-v1.11.md

docs/book/src/developer/providers/contracts/control-plane.md

@@ -1,6 +1,6 @@
 # Contract rules for ControlPlane
 
-Control plane providers MUST implement a ControlPlane resource.
+Control plane providers MUST implement a ControlPlane resource using Kubernetes' CustomResourceDefinition (CRD).
 
 The goal of a ControlPlane resource is to instantiate a Kubernetes control plane; a Kubernetes control plane
 at least contains the following components:

docs/book/src/developer/providers/contracts/infra-cluster.md

@@ -1,6 +1,6 @@
 # Contract rules for InfraCluster
 
-Infrastructure providers SHOULD implement an InfraCluster resource.
+Infrastructure providers SHOULD implement an InfraCluster resource using Kubernetes' CustomResourceDefinition (CRD).
 
 The goal of an InfraCluster resource is to supply whatever prerequisites (in term of infrastructure) are necessary for running machines.
 Examples might include networking, load balancers, firewall rules, and so on.

docs/book/src/developer/providers/contracts/infra-machine.md

@@ -1,6 +1,6 @@
 # Contract rules for InfraMachine
 
-Infrastructure providers SHOULD implement an InfraMachine resource.
+Infrastructure providers SHOULD implement an InfraMachine resource using Kubernetes' CustomResourceDefinition (CRD).
 
 The goal of an InfraMachine resource is to manage the lifecycle of a provider-specific machine instances.
 These may be physical or virtual instances, and they represent the infrastructure for Kubernetes nodes.
@@ -641,7 +641,7 @@ is implemented in InfraMachine controllers:
 [implementation best practices]: ../best-practices.md
 [infrastructure Provider Security Guidance]: ../security-guidelines.md
 [Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
-[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate_webhook.go
+[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate.go
 [Cluster API v1.11 migration notes]: ../migrations/v1.10-to-v1.11.md
 [Opt-in Autoscaling from Zero]: https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20210310-opt-in-autoscaling-from-zero.md
 [InfraMachine: pausing]: #inframachine-pausing

docs/book/src/developer/providers/contracts/ipam.md

@@ -14,7 +14,7 @@ Note that the IPAM contract is single-stack. If you need both v4 and v6 addresse
 
 ## Data Types
 
-An IPAM provider must define one or more API types for IP address pools. The types:
+An IPAM provider must define one or more API types for IP address pools using Kubernetes' CustomResourceDefinition (CRD). The types:
 
 1. Must belong to an API group served by the Kubernetes apiserver 
 2. Must be implemented as a CustomResourceDefinition. 

docs/book/src/reference/versions.md

@@ -80,6 +80,41 @@ The table below documents support matrix for Cluster API versions (versions olde
 | v1.1.x        | EOL                     | EOL since 2023-03-28 - v1.4.0 release date                                                  |
 | v1.0.x        | EOL                     | EOL since 2022-12-01 - v1.3.0 release date                                                  |
 
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+When importing Cluster API go modules as a dependency, you MUST consider any Cluster API behaviour that is not defined 
+by an API field or by a well-defined extension point, as a Cluster API internal implementation detail, and internal 
+implementation details can change at any time.
+
+Accordingly, in order to not expose users of projects importing Cluster API go modules as a dependency to the risk 
+that issue arises when one of the Cluster API internal behavior changes, you MUST NOT rely on any Cluster API 
+internal behaviours.
+
+Please note that this applies to any public go func or types; As a only and notable exception, maintainers 
+are committed to avoid as much as possible breaking changes within the same minor release for the following packages:
+- /util/*
+- /cmd/clusterctl/client 
+
+The Cluster API maintainers welcome feedback and contributions to improve project's extensibility point, 
+please [open an issue](https://github.com/kubernetes-sigs/cluster-api/issues/new?assignees=&labels=&template=feature_request.md) on the Cluster API repo or add an item to the agenda in the [Cluster API community meeting](https://git.k8s.io/community/sig-cluster-lifecycle/README.md#cluster-api).
+
+</aside>
+
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+Forks of the CLuster API project are not recommended, instead, Cluster API maintainers welcome feedback and contributions 
+to improve project's extensibility point, please [open an issue](https://github.com/kubernetes-sigs/cluster-api/issues/new?assignees=&labels=&template=feature_request.md) on the Cluster API repo or add an item 
+to the agenda in the [Cluster API community meeting](https://git.k8s.io/community/sig-cluster-lifecycle/README.md#cluster-api).
+
+If a user still wants to fork this project, please note that it is up to the user to validate if the fork works
+properly and maintainers will not provide any support or guarantee on these kind of integrations/usage.
+
+</aside>
+
 #### Skip upgrades
 
 Cluster API supports at maximum n-3 minor version skip upgrades.
@@ -286,6 +321,17 @@ See [Cluster API release support](#cluster-api-release-support) and [Kubernetes
 
 See also [Kubernetes version specific notes](#kubernetes-version-specific-notes).
 
+<aside class="note warning">
+
+<h1>Warning</h1>
+
+Cluster API is tested with upstream, fully conformant, Kubernetes releases.
+
+It might be possible to use Cluster API also with non conformant Kubernetes releases, but it is up to users
+to validate if this works and the project does not provide any support or guarantees for these kind of deployments.
+
+</aside>
+
 ### Kubeadm Bootstrap provider (`kubeadm-bootstrap-controller`) 
 
 For each version of the Cluster API core provider, there is a corresponding version of the Kubeadm Bootstrap provider.