Update api-conventions.md

1 files changed, 14 insertions, 1 deletions

diff --git a/contributors/devel/api-conventions.md b/contributors/devel/api-conventions.md
index e5a6aff8..e05224a4 100644
--- a/contributors/devel/api-conventions.md
+++ b/contributors/devel/api-conventions.md
@@ -1,7 +1,7 @@
 API Conventions
 ===============
 
-Updated: 2/23/2017
+Updated: 3/7/2017
 
 *This document is oriented at users who want a deeper understanding of the
 Kubernetes API structure, and developers wanting to extend the Kubernetes API.
@@ -1463,6 +1463,19 @@ be less than 256", "must be greater than or equal to 0".  Do not use words
 like "larger than", "bigger than", "more than", "higher than", etc.
 * When specifying numeric ranges, use inclusive ranges when possible.
 
+## Backward compatibility gotchas
+
+* A single feature/property cannot be represented using multiple spec fields in the same API version
+  simultaneously. Only one field can be populated in any resource at a time, and the client
+  needs to be able to specify which field they expect to use (typically via API version),
+  on both mutation and read. Old clients must continue to function properly while only manipulating
+  the old field. New clients must be able to function properly while only manipulating the new
+  field.
+* Validation rules on spec fields can be relaxed but not strengthened -- any requests that
+  previously worked must continue to work. The opposite is true for status fields. Note that changing
+  any validation rules always has the potential of breaking some client, since it changes the
+  assumptions about part of the API, similar to adding new enum values.
+
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/api-conventions.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->