Put in some further clarifications

Author: sbernauer

crates/stackable-versioned/src/flux_converter/apply_crd.rs

@@ -12,13 +12,18 @@ impl ApplyResource for CustomResourceDefinition {
         //    If it does not exist, then simple apply.
         //
         // 2. If the CRD already exists, then get it, and check...
-        //    - spec.conversion (this is likely to change, which is fine)
-        //    - spec.group (this should probably never change)
-        //    - spec.names (it is ok to add names, probably not great to remove them)
-        //    - spec.preserve_unknown_fields (is this ok to change?)
-        //    - spec.scope (this should probably never change)
+        //    - spec.conversion (this will often change, which is fine (e.g. caBundle rotation))
+        //    - spec.group (this should never change)
+        //    - spec.names (it is ok to add names, probably not great to remove them, but legit as
+        //      we can only keep a limited number because of CR size limitations)
+        //    - spec.preserve_unknown_fields (we can be opinionated and reject Some(false)
+        //      (and accept None and Some(true)). This is because the field is deprecated in favor
+        //      of setting x-preserve-unknown-fields to true in spec.versions\[*\].schema.openAPIV3Schema.
+        //      See https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#field-pruning
+        //      for details.
+        //    - spec.scope (this should never change)
         //
-        // 3. For spec.versions, where "A" is the sert of versions applied to the server,
+        // 3. For spec.versions, where "A" is the set of versions currently defined on the stored CRD,
         //    and "B" is the set of versions to be applied...
         //    - A - B: These versions are candidates for removal
         //    - B - A: These versions can be safely appended