diff --git a/api_compatibility_policy.md b/api_compatibility_policy.md index 36324e59a41..c5ad7934b56 100644 --- a/api_compatibility_policy.md +++ b/api_compatibility_policy.md @@ -90,26 +90,31 @@ For more information on support windows, see the [deprecations table](./docs/dep ## Feature Gates -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. -* `beta` (default) - This value indicates that only fields which are of `beta` (or greater) stability are enabled, i.e. `alpha` fields are not enabled. -* `alpha` - This value indicates that fields of all stability levels are enabled, specifically `alpha`, `beta` and `GA`. +Stability levels of feature gates are independent from CRD apiVersions. -| Feature Versions -> | v1 | beta | alpha | -|---------------------|----|------|-------| -| stable | x | | | -| beta | x | x | | -| alpha | x | x | x | +Prior to v0.53.x and the introduction of Per-feature flags, features enabled by API fields(API-driven features) at different levels of stability can be enabled using the flag `enable-api-fields`: +* `stable` - This value indicates that only fields of the highest stability level are enabled; i.e. `alpha` and `beta` fields are not enabled. + +* `beta` (default) - This value indicates that only fields which are of `beta` (or greater) stability are enabled, i.e. `alpha` fields are not enabled. + +* `alpha` - This value indicates that fields of all stability levels are enabled, specifically `alpha`, `beta` and `GA`(`stable`). See the current list of [alpha features](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.md#alpha-features) and [beta features](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.md#beta-features). +| `enable-api-fields` value | stable features enabled | beta features enabled | alpha features enabled | +|----------------------------|-------------------------|-----------------------|------------------------| +| stable | x | | | +| beta | x | x | | +| alpha | x | x | x | + +After the introduction of Per-feature flags, users are able to enable a single new feature with their dedicated feature flags. Note that the `enable-api-fields` feature flag will continue to validate all existing [beta](https://github.com/tektoncd/pipeline/blob/release-v0.52.x/docs/additional-configs.md#beta-features) and [alpha](https://github.com/tektoncd/pipeline/blob/release-v0.52.x/docs/additional-configs.md#alpha-features) features till [v0.52.x](https://github.com/tektoncd/pipeline/tree/release-v0.52.x). All new features will be guarded by their own feature flags. Instructions for adding a new per-feature flag can be found in [feature-flags.md](./docs/feature-flags.md#per-feature-flag). ### Alpha features -- Alpha feature in beta or GA CRDs are disabled by default and must be enabled by [setting `enable-api-fields` to `alpha`](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.md#alpha-features) +- Alpha features are disabled by default and must be enabled by [setting `enable-api-fields` to `alpha`](https://github.com/tektoncd/pipeline/blob/main/docs/additional-configs.md#alpha-features) - These features may be dropped or backwards incompatible changes made at any time, though one release worth of warning will be provided. @@ -125,14 +130,12 @@ See the current list of [alpha features](https://github.com/tektoncd/pipeline/bl i.e. by providing a 9 month support period. - Beta features are reviewed for promotion to GA/Stable on a regular basis. However, there is no guarantee that they will be promoted to GA/stable. - -- For beta API versions, beta is the highest level of stability possible for any feature. ### GA/Stable features -- GA/Stable features are present in a [GA CRD](#ga-crds) only. +- GA/Stable features are enabled by default. -- GA/Stable features are enabled by default +- GA/Stable features are features that have been promoted from beta to the highest level of stability. They cannot be disabled in any CRD version. - GA/Stable features will not be removed or changed in a backwards incompatible manner without incrementing the API Version. @@ -145,7 +148,7 @@ Features are first released as experimental in alpha, refined in beta, and final #### 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 change the stability level for validation to `beta`. It will continue to be disabled by default. +- The dedicated feature flag for this feature will change its stability level to `beta`. It will continue to 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. diff --git a/docs/feature-flags.md b/docs/feature-flags.md new file mode 100644 index 00000000000..347e658d039 --- /dev/null +++ b/docs/feature-flags.md @@ -0,0 +1,31 @@ +### Per-feature flag + +All new features added after [v0.53.0](https://github.com/tektoncd/pipeline/releases/tag/v0.53.0) will be enabled by dedicated feature flags. +To introduce a new feature flag for a new feature, we will follow these steps: +- Add a new per feature flag to the [configMap](./../config/config-feature-flags.yaml) and a new feature flag with Default value follwoing the `PerFeatureFlag` struct in feature_flags.go. +- Add unit tests for the new feature flag. Update all test cases where the configMap setting is needed, such as the provenance test cases. +- To add integration tests: + - First, add the tests to `pull-tekton-pipeline-alpha-integration-test`. Turn on the newly-introduced flag at [alpha test Prow environment](./../test/e2e-tests-kind-prow-alpha.env). + - When the flag is promoted to `beta` stability level, change the test to use [`beta` Prow environment setup]. + - To add tests for combinations of feature flags, add tests for all alpha-stable feature flags being turned on, with one alpha feature turned off at a time. + +### `enable-api-fields` + +Note that the `enable-api-fields` feature flag will continue to validate all current [beta](https://github.com/tektoncd/pipeline/blob/release-v0.52.x/docs/additional-configs.md#beta-features) and [alpha](https://github.com/tektoncd/pipeline/blob/release-v0.52.x/docs/additional-configs.md#alpha-features) features utill [v0.52.x] all of them have stabilized or deprecated. + +Snapshot of existent `beta` and `alpha` API-driven features as of [v0.52.x](https://github.com/tektoncd/pipeline/releases/tag/v0.52.0): +| Feature | Stability level | +| ----------------------------------------------------------------------------------------------------- | --------------- | +| [Array Results and Array Indexing](pipelineruns.md#specifying-parameters) | beta | +| [Object Parameters and Results](pipelineruns.md#specifying-parameters) | beta | +| [Remote Tasks](./taskruns.md#remote-tasks) and [Remote Pipelines](./pipelineruns.md#remote-pipelines) | beta | +| [Isolated `Step` & `Sidecar` `Workspaces`](./workspaces.md#isolated-workspaces) | beta | +| [Hermetic Execution Mode](./hermetic.md) | alpha | +| [Windows Scripts](./tasks.md#windows-scripts) | alpha | +| [Debug](./debug.md) | alpha | +| [Step and Sidecar Overrides](./taskruns.md#overriding-task-steps-and-sidecars) | alpha | +| [Matrix](./matrix.md) | alpha | +| [Task-level Resource Requirements](compute-resources.md#task-level-compute-resources-configuration) | alpha | +| [Configure Default Resolver](./resolution.md#configuring-built-in-resolvers) | alpha | + +