From 3dfffd39c8bdb3cec2879d8160cab75451e268fb Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Tue, 18 Jan 2022 10:12:19 -0500 Subject: [PATCH 1/2] Clarify deprecation rule 3 --- content/en/docs/reference/using-api/deprecation-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index 6bbd9be9e1..ae10c4dae5 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -73,11 +73,11 @@ knows how to convert between them in both directions. Additionally, any new field added in v2 must be able to round-trip to v1 and back, which means v1 might have to add an equivalent field or represent it as an annotation. -**Rule #3: An API version in a given track may not be deprecated until a new -API version at least as stable is released.** +**Rule #3: An API version in a given track may not be deprecated in favor of a less stable API version.** -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. + * GA API versions can replace beta and alpha API versions. + * Beta API versions can replace earlier beta and alpha API versions, but *may not* replace GA API versions. + * Alpha API versions can replace earlier alpha API versions, but *may not* replace GA or beta API versions. **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 From b828365a0e24275c3295ba94b716b8b1c441b0a3 Mon Sep 17 00:00:00 2001 From: Jordan Liggitt Date: Tue, 18 Jan 2022 10:13:13 -0500 Subject: [PATCH 2/2] Change deprecation rule 4a to make stable APIs permanent within a major version --- .../reference/using-api/deprecation-policy.md | 34 ++++++------------- 1 file changed, 10 insertions(+), 24 deletions(-) diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index ae10c4dae5..e1c378c4ac 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -79,15 +79,17 @@ might have to add an equivalent field or represent it as an annotation. * Beta API versions can replace earlier beta and alpha API versions, but *may not* replace GA API versions. * Alpha API versions can replace earlier alpha API versions, but *may not* replace GA or beta API versions. -**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:** +**Rule #4a: minimum API lifetime is determined by the API stability level** - * **GA: 12 months or 3 releases (whichever is longer)** - * **Beta: 9 months or 3 releases (whichever is longer)** - * **Alpha: 0 releases** + * **GA API versions may be marked as deprecated, but must not be removed within a major version of Kubernetes** + * **Beta API versions must be supported for 9 months or 3 releases (whichever is longer) after deprecation** + * **Alpha API versions may be removed in any release without prior deprecation notice** -This covers the [maximum supported version skew of 2 releases](/docs/setup/release/version-skew-policy/). +This ensures beta API support covers the [maximum supported version skew of 2 releases](/docs/setup/release/version-skew-policy/). + +{{< note >}} +There are no current plans for a major version revision of Kubernetes that removes GA APIs. +{{< /note >}} {{< note >}} Until [#52185](https://github.com/kubernetes/kubernetes/issues/52185) is @@ -237,7 +239,7 @@ API versions are supported in a series of subsequent releases. @@ -267,22 +269,6 @@ API versions are supported in a series of subsequent releases. - - X+16 - v2, v1 (deprecated) - v2 - - - - X+17 - v2 - v2 - - - -