Merge pull request #35440 from smarterclayton/clarify_compat

Automatic merge from submit-queue Clarify backwards and forwards compatibility in docs We weren't necessarily clear that we consider both required. @eparis @kubernetes/api-review-team @bgrant0607 This came up during a discussion of changing an API and I thought it was important to clarify.

Merge pull request #35440 from smarterclayton/clarify_compat
a457cf49 · Kubernetes Submit Queue · GitHub · 4f072f7a · d2ea4d51 · a457cf49
Commit a457cf49 authored Oct 24, 2016 by Kubernetes Submit Queue Committed by GitHub Oct 24, 2016
Hide whitespace changes
Inline Side-by-side

Showing with 7 additions and 3 deletions

api_changes.md docs/devel/api_changes.md +7 -3

No files found.
--- a/docs/devel/api_changes.md
+++ b/docs/devel/api_changes.md
@@ -129,8 +129,11 @@ backward-compatibly.
 ## On compatibility

 Before talking about how to make API changes, it is worthwhile to clarify what
-we mean by API compatibility.  An API change is considered backward-compatible
-if it:
+we mean by API compatibility.  Kubernetes considers forwards and backwards
+compatibility of its APIs a top priority.
+
+An API change is considered forward and backward-compatible if it:
+
   * adds new functionality that is not required for correct behavior (e.g.,
 does not add a new required field)
   * does not change existing semantics, including:
@@ -150,7 +153,8 @@ versions and back) with no loss of information.
 continue to function as they did previously, even when your change is utilized.

 If your change does not meet these criteria, it is not considered strictly
-compatible.
+compatible, and may break older clients, or result in newer clients causing
+undefined behavior.

 Let's consider some examples. In a hypothetical API (assume we're at version
 v6), the `Frobber` struct looks something like this: