Add Per-feature Flag Struct for New Features

This commit adds the per-feature flag struct and documentations for
new features in TektonCD pipeline.

part of: TEP-0138

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.

docs/feature-flags.md

@@ -0,0 +1,14 @@
+### 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.

pkg/apis/config/feature_flags.go

@@ -27,12 +27,18 @@ import (
 )
 
 const (
-	// StableAPIFields is the value used for "enable-api-fields" when only stable APIs should be usable.
+	// StableAPIFields is the value used for API-driven features of stable stability level.
 	StableAPIFields = "stable"
-	// AlphaAPIFields is the value used for "enable-api-fields" when alpha APIs should be usable as well.
+	// AlphaAPIFields is the value used for API-driven features of alpha stability level.
 	AlphaAPIFields = "alpha"
-	// BetaAPIFields is the value used for "enable-api-fields" when beta APIs should be usable as well.
+	// BetaAPIFields is the value used for API-driven features of beta stability level.
 	BetaAPIFields = "beta"
+	// Features of "alpha" stability level are disabled by default
+	DefaultAlphaFeatureEnabled = false
+	// Features of "beta" stability level are disabled by default
+	DefaultBetaFeatureEnabled = true
+	// Features of "stable" stability level are enabled by default
+	DefaultStableFeatureEnabled = true
 	// FailNoMatchPolicy is the value used for "trusted-resources-verification-no-match-policy" to fail TaskRun or PipelineRun
 	// when no matching policies are found
 	FailNoMatchPolicy = "fail"
@@ -343,3 +349,15 @@ func GetVerificationNoMatchPolicy(ctx context.Context) string {
 func IsSpireEnabled(ctx context.Context) bool {
 	return FromContextOrDefaults(ctx).FeatureFlags.EnforceNonfalsifiability == EnforceNonfalsifiabilityWithSpire
 }
+
+type PerFeatureFlag struct {
+	// Name of the feature flag
+	Name string
+	// Stability level of the feature, one of StableAPIFields, BetaAPIFields or AlphaAPIFields
+	Stability string
+	// Enabled is whether the feature is turned on
+	Enabled bool
+	// Deprecated indicates whether the feature is deprecated
+	// +optional
+	Deprecated bool
+}