📖 Improve documentation about contract version

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

@@ -146,6 +146,15 @@ labels:
 
 An example of this is in the [Kubeadm Bootstrap provider](https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/controlplane/kubeadm/config/crd/kustomization.yaml).
 
+<aside  class="note warning">
+
+<h1>Important</h1>
+
+If the provider implements the [clusterctl provider contract], the contract version defined in the
+label above must be consistent with the contract version defined in the `metadata.yaml` file.
+
+</aside>
+
 ### BootstrapConfig, BootstrapConfigList resource definition
 
 You MUST define a BootstrapConfig resource.

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

@@ -205,6 +205,20 @@ releaseSeries:
   contract: v1alpha2
 ```
 
+<aside  class="note warning">
+
+<h1>Important</h1>
+
+The contract version for a specific release series must match the contract version that is declared in the CRD for different provider's objects.
+
+More specifically, you can consider the contract version in `metadata.yaml` as a “preview” of the contract version supported by the provider, 
+but this value is used only during `clusterctl init` or `clusterctl upgrade`, not at runtime.
+
+At runtime, the system will use the contract version that is defined in the provider's CRD that are installed in the cluster.
+See contract rules for different providers for more details.
+
+</aside>
+
 #### Validation Rules
 
 Starting from clusterctl v1.11, the metadata YAML file is subject to strict validation to ensure consistency and prevent configuration errors. The following validation rules are enforced:

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

@@ -172,6 +172,15 @@ labels:
 
 An example of this is in the [Kubeadm Bootstrap provider](https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/controlplane/kubeadm/config/crd/kustomization.yaml).
 
+<aside  class="note warning">
+
+<h1>Important</h1>
+
+If the provider implements the [clusterctl provider contract], the contract version defined in the
+label above must be consistent with the contract version defined in the `metadata.yaml` file.
+
+</aside>
+
 ### ControlPlane, ControlPlaneList resource definition
 
 You MUST define a ControlPlane resource.

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

@@ -155,6 +155,15 @@ labels:
 
 An example of this is in the [Kubeadm Bootstrap provider](https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/controlplane/kubeadm/config/crd/kustomization.yaml).
 
+<aside  class="note warning">
+
+<h1>Important</h1>
+
+If the provider implements the [clusterctl provider contract], the contract version defined in the
+label above must be consistent with the contract version defined in the `metadata.yaml` file.
+
+</aside>
+
 ### InfraCluster, InfraClusterList resource definition
 
 You MUST define a InfraCluster resource.

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

@@ -147,6 +147,15 @@ labels:
 
 An example of this is in the [Kubeadm Bootstrap provider](https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/controlplane/kubeadm/config/crd/kustomization.yaml).
 
+<aside  class="note warning">
+
+<h1>Important</h1>
+
+If the provider implements the [clusterctl provider contract], the contract version defined in the
+label above must be consistent with the contract version defined in the `metadata.yaml` file.
+
+</aside>
+
 ### InfraMachine, InfraMachineList resource definition
 
 You MUST define a InfraMachine resource.

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

@@ -143,6 +143,15 @@ labels:
 
 An example of this is in the [AWS infrastructure provider](https://github.com/kubernetes-sigs/cluster-api-provider-aws/blob/main/config/crd/kustomization.yaml).
 
+<aside  class="note warning">
+
+<h1>Important</h1>
+
+If the provider implements the [clusterctl provider contract], the contract version defined in the
+label above must be consistent with the contract version defined in the `metadata.yaml` file.
+
+</aside>
+
 ### InfraMachinePool, InfraMachinePoolList resource definition
 
 You MUST define a InfraMachinePool resource if you provider supports MachinePools.

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

@@ -2925,6 +2925,9 @@ metadata:
   name: <your CRD name>
 ```
 
+4. If the provider implements the [clusterctl provider contract](../contracts/clusterctl.md), then the contract version defined 
+   in the `metadata.yaml` file must be changed aligning to the contract version the CRD.
+
 ### How to bump to CAPI V1.11 but keep using deprecated v1beta1 conditions
 
 A provider can continue to use deprecated v1beta1 conditions also after bumping to CAPI V1.11, but to do