api: Explain how to adapt to visibility changes in future APIs

internal/api/v20240610preview/register.go

@@ -31,6 +31,17 @@ func EnumValidateTag[S ~string](values ...S) string {
 }
 
 func init() {
+	// NOTE: If future versions of the API expand field visibility, such as
+	//       a field with @visibility("read","create") becoming updatable,
+	//       then earlier versions of the API will need to override their
+	//       StructTagMap to maintain the original visibility flags. This
+	//       is where such overrides should happen, along with a comment
+	//       about what changed and when. For example:
+	//
+	//       // This field became updatable in version YYYY-MM-DD.
+	//       clusterStructTagMap["Properties.Spec.FieldName"] = reflect.StructTag("visibility:\"read create\"")
+	//
+
 	api.Register(version{})
 
 	// Register enum type validations