github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-07-25 20:53:33 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #35440 from smarterclayton/clarify_compat

Browse Source 
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.
This commit is contained in:
Kubernetes Submit Queue 2016-10-24 13:38:55 -07:00 committed by GitHub
commit a457cf49f4
1 changed files with 7 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/devel/api_changes.md
View File

@ -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: