rename to migrationPolicies

Signed-off-by: lsviben <sviben.lovro@gmail.com>

design/one-pager-ignore-changes.md

@@ -58,7 +58,7 @@ for ignoring some managed resource parameters during updates.
 
 ## Proposal
 
-Proposed solution is to rework the new [managementPolicy] field which came
+Proposed solution is to rework the new [managementPolicy] feature which came
 with the [ObserveOnly] feature and transform it into a set of enum values
 representing what Crossplane should do with the managed resource.
 
@@ -76,6 +76,10 @@ representing what Crossplane should do with the managed resource.
 This will allow users to fine-tune how Crossplane manages the external
 resource, in a manner which is very explicit and easy to understand.
 
+To avoid breaking the existing managed resources, the name of the new field
+will be `managementPolicies` while the old one will be deprecated and
+eventually removed.
+
 Some examples on how the management policies would work and how they would
 replace the current `managementPolicy` and `deletionPolicy`:
 
@@ -87,34 +91,34 @@ spec:
 
 # would be replaced with:
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe", "LateInitialize"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe", "LateInitialize"]
   # or
-  managementPolicy: ["*"]
+  managementPolicies: ["*"]
 
 # ObserveOnly
 spec:
   managmentPolicy: ObserveOnly
 
 # would be replaced with:
 spec:
-  managementPolicy: ["Observe"]
+  managementPolicies: ["Observe"]
 
 # OrphanOnDelete
 spec:
   managementPolicy: OrphanOnDelete
 
 # would be replaced with:
 spec:
-  managementPolicy: ["Create", "Update", "Observe", "LateInitialize"]
+  managementPolicies: ["Create", "Update", "Observe", "LateInitialize"]
 
 # pause can be achieved by setting managementPolicy to empty list instead of
 # using the annotation
 spec:
-  managementPolicy: []
+  managementPolicies: []
 
 # Turn off late initialization
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe"]
 ```
 
 In addition to the new management policy, we will also add a new field
@@ -148,7 +152,7 @@ meant that if the `deletionPolicy` was set to `Orphan`, and the
 orphaned.
 
 In the new design, we could still follow this approach, by orphaning the
-resource even if the `managementPolicy` includes `Delete`, if the
+resource even if the `managementPolicies` include `Delete`, if the
 `deletionPolicy` is set to `Orphan`, until we entirely remove the deletion
 policy.
 
@@ -170,9 +174,9 @@ future-proof.
 The `managementPolicy` feature is alpha, so it should be ok to change the
 API. We should still offer a migration path for existing resources. The
 combinations of `managementPolicy` and `deletionPolicy` should be migrated
-to the new `managementPolicy` field.
+to the new `managementPolicies` field.
 
-| managementPolicy | deletionPolicy | new management policy                             |
+| managementPolicy | deletionPolicy | managementPolicies                                |
 |------------------|----------------|---------------------------------------------------|
 | FullControl      | Delete         | ["*"]                                             |
 | FullControl      | Orphan         | ["Create", "Update", "Observe", "LateInitialize"] |
@@ -181,6 +185,10 @@ to the new `managementPolicy` field.
 | ObserveOnly      | Delete         | ["Observe"]                                       |
 | ObserveOnly      | Orphan         | ["Observe"]                                       |
 
+We would keep the deprecated `managementPolicy` field for a release cycle, to
+allow for migrations. If agreed, we can provide a migration tool that would
+migrate the resources to the new `managementPolicies` field.
+
 ### initProvider
 
 The idea here was to have a field that would be used only during creation,
@@ -245,7 +253,7 @@ policy.
 
 ```yaml
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe"]
   forProvider:
     maxSize: 5
     minSize: 1
@@ -262,7 +270,7 @@ would need to be used alongside omitting `LateInitialize` management policy.
 
 ```yaml
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe"]
   initProvider:
     readCapacity: 1
     writeCapacity: 1
@@ -279,7 +287,7 @@ the autoscaler would be able to control the `desiredSize` after creation.
 
 ```yaml
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe"]
   initProvider:
     scalingConfig:
       desiredSize: 1
@@ -297,7 +305,7 @@ Just omitting the `LateInitialize` management policy would be enough as the
 
 ```yaml
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe"]
   forProvider:
   ...
 ```
@@ -311,7 +319,7 @@ omitting the `LateInitialize` management policy.
 Example:
 ```yaml
 spec:
-  managementPolicy: ["Create", "Update", "Delete", "Observe"]
+  managementPolicies: ["Create", "Update", "Delete", "Observe"]
   initProvider:
     members:
       - user1