From cf50213d42f57ab227ad46d4758d657ed4bf7056 Mon Sep 17 00:00:00 2001 From: Jerome Ju Date: Mon, 28 Aug 2023 11:28:51 -0400 Subject: [PATCH] [WIP] RFC: Add feature graduation process documentation This commit adds the feature graduation process documentation to the API compatibility policy. It aims to mitigate the confusions of API versioning that was coupled with feature versioning as in #6592. related: TEP0138 --- api_compatibility_policy.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md index 0f77c60d892..8a3690095fa 100644 --- a/api_compatibility_policy.md +++ b/api_compatibility_policy.md @@ -90,6 +90,12 @@ For more information on support windows, see the [deprecations table](./docs/dep ## Feature Gates +For new features, we are adding new pre feature flag for each feature. + +Note that feature stability and API versions should be irreleavant to each other per [TEP-0138]. + +* Existing features might be guard + CRD API versions gate the overall stability of the CRD and its default behaviors. Within a particular CRD version, certain opt-in features may be at a lower stability level as described in [TEP-33](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md). These fields may be disabled by default and can be enabled by setting the right `enable-api-fields` feature-flag as described in TEP-33: * `stable` - This value indicates that only fields of the highest stability level are enabled; For `beta` CRDs, this means only beta stability fields are enabled, i.e. `alpha` fields are not enabled. For `GA` CRDs, this means only `GA` fields are enabled, i.e. `beta` and `alpha` fields would not be enabled. TODO(#6592): Decouple feature stability from API stability. @@ -136,6 +142,21 @@ See the current list of [alpha features](https://github.com/tektoncd/pipeline/bl - GA/Stable features will not be removed or changed in a backwards incompatible manner without incrementing the API Version. +### Feature Graduation Process +Features start as experimental in alpha, are refined in beta, and are finalized in stable releases. + +#### Introducing an `alpha` feature +- When a feature is first introduced to Tekton, it will have the `alpha` stability level and be disabled by default. +- At this stage, users could choose to experiment with the feature. Feedback will be collected from users and it will help maintainers to determine whether to promote the feature to higher stability level or deprecate it. + +#### Promoting a feature to `beta` +- After feedback of the usage of the alpha features, once the needs and motivations are validated, a feature could be promoted to `beta`. This stage is where features are further tested and refined. +- The dedicated feature flag for this feature will then change the stability level only. It will still be disabled by default. + +#### Graduating a feature to `stable` +- This is the final stage of feature graduation process, where features are considered to be complete and ready to be released for the public. +- Once a feature has graduated to `stable`, it will be turned on by default. + ## Approving API changes API changes must be approved by [OWNERS](OWNERS). The policy is slightly different