From 0347d2388f59325fd9e8c2de2c2ac3ed1407362d Mon Sep 17 00:00:00 2001 From: Silvia Teresa Sandy Martinez Date: Thu, 8 Nov 2018 11:57:43 +0100 Subject: [PATCH] =?UTF-8?q?Added=20feature-gates=20deprecation=20guideline?= =?UTF-8?q?s=20and=20policy=20as=20per=20discussi=E2=80=A6=20(#10294)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added feature-gates deprecation guidelines and policy as per discussion: SIG-architecture meeting * Update deprecation-policy.md Fixes and initial feedback incorporated. * Removed unneeded sentence Removed complicated sentence that is better phrased one sentence later. * Incorporated feedback - Sept 22nd. Re-structured following key ideas from the feedback. * Fixed nits 7th October Fixed nits 7th October * Incorporated feedback Oct 25th Incorporated 'invocation triggers warning' and what to do when disabling a no-op. * fixed "tide" Announced for completed * Incorporated feedback from sig docs --- .../reference/using-api/deprecation-policy.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index 31cc4a6db2..a6a8f190cd 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -365,6 +365,56 @@ This applies only to significant, user-visible behaviors which impact the correctness of applications running on Kubernetes or that impact the administration of Kubernetes clusters, and which are being removed entirely. +An exception to the above rule is _feature gates_. Feature gates are key=value +pairs that allow for users to enable/disable experimental features. + +Feature gates are intended to cover the development life cycle of a feature - they +are not intended to be long-term APIs. As such, they are expected to be deprecated +and removed after a feature becomes GA or is dropped. + +As a feature moves through the stages, the associated feature gate evolves. +The feature life cycle matched to its corresponding feature gate is: + + * Alpha: the feature gate is disabled by default and can be enabled by the user. + * Beta: the feature gate is enabled by default and can be disabled by the user. + * GA: the feature gate is deprecated (see ["Deprecation"](#deprecation)) and becomes + non-operational. + * GA, deprecation window complete: the feature gate is removed and calls to it are + no longer accepted. + +### Deprecation + +Features can be removed at any point in the life cycle prior to GA. When features are +removed prior to GA, their associated feature gates are also deprecated. + +When an invocation tries to disable a non-operational feature gate, the call fails in order +to avoid unsupported scenarios that might otherwise run silently. + +In some cases, removing pre-GA features requires considerable time. Feature gates can remain +operational until their associated feature is fully removed, at which point the feature gate +itself can be deprecated. + +When removing a feature gate for a GA feature also requires considerable time, calls to +feature gates may remain operational if the feature gate has no effect on the feature, +and if the feature gate causes no errors. + +Features intended to be disabled by users should include a mechanism for disabling the +feature in the associated feature gate. + +Versioning for feature gates is different from the previously discussed components, +therefore the rules for deprecation are as follows: + +**Rule #8: Feature gates must be deprecated when the corresponding feature they control +transitions a lifecycle stage as follows. Feature gates must function for no less than:** + + * **Beta feature to GA: 6 months or 2 releases (whichever is longer)** + * **Beta feature to EOL: 3 months or 1 release (whichever is longer)** + * **Alpha feature to EOL: 0 releases** + +**Rule #9: Deprecated feature gates must respond with a warning when used. When a feature gate +is deprecated it must be documented in both in the release notes and the corresponding CLI help. +Both warnings and documentation must indicate whether a feature gate is non-operational.** + ## Exceptions No policy can cover every possible situation. This policy is a living