From 8f9677227dac0d0032a9faaae1dd318e8ddbd095 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Thu, 7 Sep 2017 11:04:59 -0700 Subject: [PATCH] Update deprecation doc with default versions --- docs/reference/deprecation-policy.md | 147 ++++++++++++++++++++++----- 1 file changed, 123 insertions(+), 24 deletions(-) diff --git a/docs/reference/deprecation-policy.md b/docs/reference/deprecation-policy.md index fecd3484da..241eea0740 100644 --- a/docs/reference/deprecation-policy.md +++ b/docs/reference/deprecation-policy.md @@ -70,41 +70,124 @@ API version at least as stable is released.** GA API versions can replace GA API versions as well as beta and alpha API versions. Beta API versions *may not* replace GA API versions. -**Rule #4: Other than the most recent API versions in each track, older API +**Rule #4a: Other than the most recent API versions in each track, older API versions must be supported after their announced deprecation for a duration of no less than:** * **GA: 1 year or 2 releases (whichever is longer)** - * **Beta: 3 months or 1 release (whichever is longer)** + * **Beta: 6 months or 2 releases (whichever is longer)** * **Alpha: 0 releases** -This is best illustrated by example. Imagine a Kubernetes release, version X, -which supports a particular API group. A new Kubernetes release is made every -approximately 3 months (4 per year). The following table describes which API -versions are supported in a series of subsequent releases. +NOTE: Until [#52185](https://github.com/kubernetes/kubernetes/issues/52185) is +resolved, no API versions may be removed. + +**Rule #4b: The "preferred" API version and the "storage version" for a given +group may not advance util after a release has been made that supports both the +new version and the previous version** + +Users must be able to upgrade to a new release of Kubernetes and then roll back +to a previous release, without converting anything to the new API version or +suffering breakages (unless they explicitly used features only available in the +newer version). This is particularly evident in the stored representation of +objects. + +All of this is best illustrated by examples. Imagine a Kubernetes release, +version X, which introduces a new API group. A new Kubernetes release is made +every approximately 3 months (4 per year). The following table describes which +API versions are supported in a series of subsequent releases. + - + + - - + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + - - + + + - - + + + - - + + + + + + + + + - - + + + - - + + + - + +
Release API VersionsPreferred/Storage Version Notes
Xv1v1alpha1v1alpha1
X+1v1, v2alpha1v1alpha2v1alpha2 +
    +
  • v1alpha1 is removed, "action required" relnote
    • +
+
X+2v1, v2alpha2v1beta1v1beta1 +
    +
  • v1alpha2 is removed, "action required" relnote
    • +
+
X+3v1beta2, v1beta1 (deprecated)v1beta1 +
    +
  • v1beta1 is deprecated, "action required" relnote
    • +
+
X+4v1beta2, v1beta1 (deprecated)v1beta2
X+5v1, v1beta2 (deprecated)v1beta2 +
    +
  • v1beta1 is removed, "action required" relnote
    • +
  • v1beta2 is deprecated, "action required" relnote
    • +
+
X+6v1, v1beta2 (deprecated)v1 +
    +
+
X+7v1v1 +
    +
  • v1beta2 is removed, "action required" relnote
    • +
+
X+8v2alpha1, v1v1
X+9v2alpha2, v1v1
  • v2alpha1 is removed, "action required" relnote
    • @@ -112,8 +195,9 @@ versions are supported in a series of subsequent releases.
X+3v1, v2beta1X+10v2beta1, v1v1
  • v2alpha2 is removed, "action required" relnote
    • @@ -121,8 +205,9 @@ versions are supported in a series of subsequent releases.
X+4v1, v2beta1, v2beta2X+11v2beta2, v2beta1 (deprecated), v1v1
  • v2beta1 is deprecated, "action required" relnote
    • @@ -130,19 +215,30 @@ versions are supported in a series of subsequent releases.
X+5v1, v2, v2beta2X+12v2, v2beta2 (deprecated), v2beta1 (deprecated), v1 (deprecated)v1
    -
  • v2beta1 is removed, "action required" relnote
  • v2beta2 is deprecated, "action required" relnote
  • v1 is deprecated, "action required" relnote
X+6v1, v2X+13v2, v2beta2 (deprecated), v1 (deprecated)v2 +
    +
  • v2beta1 is removed, "action required" relnote
    • +
+
X+14v2, v1 (deprecated)v2
  • v2beta2 is removed, "action required" relnote
    • @@ -150,17 +246,20 @@ versions are supported in a series of subsequent releases.
X+7v1, v2X+15v2, v1 (deprecated)v2
X+8v1, v2X+16v2, v1 (deprecated)v2
X+9X+17v2 v2