Merge pull request #2686 from thockin/defaults-for-new-fields-rule

Clarify rules around defaults across versions

1 files changed, 8 insertions, 9 deletions

diff --git a/contributors/devel/api_changes.md b/contributors/devel/api_changes.md
index fa53adb2..e3a9127d 100644
--- a/contributors/devel/api_changes.md
+++ b/contributors/devel/api_changes.md
@@ -336,15 +336,14 @@ worked before the change.
   release, and do not make it the storage version. The latter is necessary so that a rollback of the
   apiserver doesn't render resources in etcd undecodable after rollback.
 
-* Any field with a default value in one API version must have *non-nil default
-  values* in all API versions. If a default value is added to a field in one API
-  version, and the field didn't have a default value in previous API versions,
-  it is required to add a default value semantically equivalent to an unset
-  value to the field in previous API versions, to preserve the semantic
-  meaning of the value being unset. This includes:
-  * a new optional field with a default value is introduced in a new API version
-  * an old optional field without a default value (i.e. can be nil) has a
-    default value in a new API version
+* Any field with a default value in one API version must have a *non-nil* default
+  value in all API versions.  This can be split into 2 cases:
+  * Adding a new API version with a default value for an existing non-defaulted
+    field: it is required to add a default value semantically equivalent to
+    being unset in all previous API versions, to preserve the semantic meaning
+    of the value being unset.
+  * Adding a new field with a default value: the default values must be
+    semantically equivalent in all currently supported API versions.
 
 ## Incompatible API changes