📖 Small improvements to migration instructions (#12328)

* Small improvements to migration instructions

* More improvements

* Address comments

* Address more feedback

Author: fabriziopandini

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

@@ -44,6 +44,8 @@ proposal because most of the changes described below are a consequence of the wo
       * [Stage 1](#stage-1-)
       * [Stage 2](#stage-2)
       * [Stage 3](#stage-3)
+  * [Annex](#annex)
+    * [Imports for conditions and patch helper utils](#imports-for-conditions-and-patch-helper-utils)
 <!-- TOC -->
 
 ## Go version
@@ -510,7 +512,14 @@ As documented in [Suggested changes for providers](#suggested-changes-for-provid
   Please refer to [API Changes](#api-changes) for more details about the changes introduced by this release.
 
   Note: it is technically possible for providers to keep using v1beta1 types from CAPI v1.11, but this is 
-  not recommended (this approach was not tested during the implementation, we don't know if there are road blockers). 
+  not recommended because it will lead to additional conversion calls.
+
+  Additionally, in v1.11 all the CAPI utils like e.g. `IsControlPlaneMachine` are now using v1beta2 API types. 
+  This might lead to additional work for providers to keep using v1beta1 types from CAPI v1.11 (you have to fork
+  all utils the provider is using from an older CAPI release or replace them with something else).
+  
+  Last but not least, please be aware that given the issues above, this approach was not tested during the implementation, 
+  and we don't know if there are road blockers.
 
 - If providers are using Conditions from Cluster API resources, e.g. by looking at the ControlPlaneInitialized condition
   on the Cluster object, we highly recommend providers to use new conditions instead of old ones.
@@ -618,20 +627,24 @@ into:
 ```go
 import (
 	...
-    conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions"
-    patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch"
+    v1beta1conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions"
+    v1beta1patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch"
 )
 ```
 
+Important! 
+Please pay special attention to use `sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch` import everywhere,
+because using `sigs.k8s.io/cluster-api/util/patch` by mistake could in some cases lead to dropping conditions at runtime.
+
 Also, please note that starting from the CAPI release when v1beta1 removal will happen (tentative Aug 2026), the Cluster API project
 will remove the Cluster API condition type, the `util/conditions/deprecated/v1beta1` package, the `util/deprecated/v1beta1` package,
 the code handling old conditions in `util/patch.Helper` and everything related to the custom Cluster API custom condition type.
 
 This means that if a provider wants to keep using deprecated v1beta1 conditions after this date, they have to maintain their
 own custom copy of the types and related utils.
 
-Please also note that the v1beta2 contract is not going to require a specific condition types, so it will be also possible
-to use different custom conditions types,
+Also note that the v1beta2 contract is not going to require a specific condition type, so it will be also possible
+to use a custom condition type,
 
 See [Suggested changes for providers](#suggested-changes-for-providers) and [Cluster API Contract changes](#cluster-api-contract-changes)
 for more details.
@@ -652,19 +665,22 @@ If you are at this stage, you must use following util packages from CAPI v1.11 (
 ```go
 import (
 	...
-    conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions"
+    v1beta1conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions"
     v1beta2conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions/v1beta2"
-    patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch"
+    v1beta1patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch"
 )
 ```
 
-- the `conditions` package alias provides access to utils for managing `clusterv1beta1.Conditions` in `status.conditions`
+- the `v1beta1conditions` package alias provides access to utils for managing `clusterv1beta1.Conditions` in `status.conditions`
 - the `v1beta2conditions` package alias provides access to utils for managing `metav1.Conditions` in `status.v1beta2.conditions`
-- the `patch` package alias provides access to utils for patching objects in this phase.
+- the `v1beta1patch` package alias provides access to utils for patching objects in this phase.
 
 Important!
-All packages from the import above (all packages below `sigs.k8s.io/cluster-api/util/deprecated/v1beta1`) are going
-to be removed from CAPI when the v1beta1 removal will happen (tentative Aug 2026).
+- Please pay special attention to use `sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch` import everywhere,
+  because using `sigs.k8s.io/cluster-api/util/patch` by mistake could in some cases lead to dropping conditions at runtime
+  (note: `sigs.k8s.io/cluster-api/util/patch` is the package we assume you are using before stage 1).
+- All packages from the import above (all packages below `sigs.k8s.io/cluster-api/util/deprecated/v1beta1`) are going
+  to be removed from CAPI when the v1beta1 removal will happen (tentative Aug 2026).
 
 #### Stage 2
 
@@ -678,18 +694,21 @@ If you are at this stage, you must use following util packages from CAPI v1.11 (
 import (
 	...
     "sigs.k8s.io/cluster-api/util/conditions"
-    v1beta1conditions "sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1"
+    deprecatedv1beta1conditions "sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1"
     "sigs.k8s.io/cluster-api/util/patch"
 )
 ```
 
 - the `conditions` package provides access to utils for managing `metav1.Conditions` in `status.conditions`
-- the `v1beta1conditions` package alias provides access to utils for managing `clusterv1beta2.Conditions` in `status.deprecated.v1beta1.conditions`
+- the `deprecatedv1beta1conditions` package alias provides access to utils for managing `clusterv1.Conditions` in `status.deprecated.v1beta1.conditions`
 - the `patch` package provides access to utils for patching objects in this phase
 
 Important!
-The package `sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1`" is going to be removed from CAPI when the
-v1beta1 removal will happen (tentative Aug 2026).
+- Please pay special attention to use `sigs.k8s.io/cluster-api/util/patch` import everywhere,
+  because using `sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch` by mistake could in some cases lead to dropping conditions at runtime
+  (note: `sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch` is the package you were using in stage 1, it should not be used in stage 2).
+- The package `sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1`" is going to be removed from CAPI when the
+  v1beta1 removal will happen (tentative Aug 2026).
 
 #### Stage 3
 
@@ -707,3 +726,27 @@ import (
 
 - the `conditions` package provides access to utils for managing `metav1.Conditions` in `status.conditions`
 - the `patch` package provides access to utils for patching objects in this phase
+
+Important!
+- Please pay special attention to use `sigs.k8s.io/cluster-api/util/patch` import everywhere,
+  because using `sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch` by mistake could in some cases lead to dropping conditions at runtime
+  (note: `sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch` is the package in stage 1, if should not be used in following stages).
+
+## Annex
+
+### Imports for conditions and patch helper utils
+
+In order to help users to transition away from the CAPI conditions type, CAPI v1.11 supports
+different versions of conditions and patch helper utils.
+
+Following table should help to pick the right utils.
+
+| Field to change                                                       | Import for condition util                                                                  | Import for patch helper                                                |
+|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
+| `status.conditions` of type `clusterv1beta1.Conditions`               | `v1beta1conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions"`           | `v1beta1patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch"` |
+| `status.v1beta2.conditions` of type `[]metav1.Conditions`             | `v1beta2conditions "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/conditions/v1beta2"`   | `v1beta1patch "sigs.k8s.io/cluster-api/util/deprecated/v1beta1/patch"` |
+| `status.deprecated.v1beta1.conditions` of type `clusterv1.Conditions` | `deprecatedv1beta1conditions "sigs.k8s.io/cluster-api/util/conditions/deprecated/v1beta1"` | `"sigs.k8s.io/cluster-api/util/patch"`                                 |
+| `status.conditions` of type `[]metav1.Conditions`                     | `"sigs.k8s.io/cluster-api/util/conditions"`                                                | `"sigs.k8s.io/cluster-api/util/patch"`                                 |
+Important!
+- Please pay special attention to use the correct patch helper import everywhere, because using a wrong
+  one could in some cases lead to dropping conditions at runtime while not having compile errors.