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 Versions | +Preferred/Storage Version | Notes | ||
|---|---|---|---|---|---|
| X | -v1 | +v1alpha1 | +v1alpha1 | ||
| X+1 | -v1, v2alpha1 | -+ | v1alpha2 | +v1alpha2 | +
+
|
| X+2 | -v1, v2alpha2 | +v1beta1 | +v1beta1 | +
+
|
+ |
| X+3 | +v1beta2, v1beta1 (deprecated) | +v1beta1 | +
+
|
+ ||
| X+4 | +v1beta2, v1beta1 (deprecated) | +v1beta2 | ++ | ||
| X+5 | +v1, v1beta2 (deprecated) | +v1beta2 | +
+
|
+ ||
| X+6 | +v1, v1beta2 (deprecated) | +v1 | +
+
|
+ ||
| X+7 | +v1 | +v1 | +
+
|
+ ||
| X+8 | +v2alpha1, v1 | +v1 | ++ | ||
| X+9 | +v2alpha2, v1 | +v1 |
|
||
| X+3 | -v1, v2beta1 | +X+10 | +v2beta1, v1 | +v1 |
|
| X+4 | -v1, v2beta1, v2beta2 | +X+11 | +v2beta2, v2beta1 (deprecated), v1 | +v1 |
|
| X+5 | -v1, v2, v2beta2 | +X+12 | +v2, v2beta2 (deprecated), v2beta1 (deprecated), v1 (deprecated) | +v1 |
|
| X+6 | -v1, v2 | +X+13 | +v2, v2beta2 (deprecated), v1 (deprecated) | +v2 | +
+
|
+
| X+14 | +v2, v1 (deprecated) | +v2 |
|
||
| X+7 | -v1, v2 | +X+15 | +v2, v1 (deprecated) | +v2 | |
| X+8 | -v1, v2 | +X+16 | +v2, v1 (deprecated) | +v2 | |
| X+9 | +X+17 | +v2 | v2 |
|