TEP-0138: Improve Tekton Pipeline Feature Flags

This commit adds the problem statement for improving Tekton Pipeline Feature
Flags.

teps/0033-tekton-feature-gates.md

@@ -1,5 +1,7 @@
 ---
 status: implemented
+superseded-by:
+- TEP-0138
 title: Tekton Feature Gates
 creation-date: '2020-11-20'
 last-updated: '2021-12-16'

teps/0138-improve-tekton-pipeline-feature-flag.md

@@ -33,9 +33,7 @@ New features in Tekton start at "`alpha`" stability and can be promoted to `beta
   - Since features at a lower stability level tend to have more bugs, cluster operators and vendors may want to limit usage of lower-stability features they do not need, while still being able to enable individual features for specific use cases.
   - Enabling all alpha features may have led to problems with the usage and debugging of stable and beta features. For example, in [alpha object param feature causes problems for debugging beta resolver features](https://github.com/tektoncd/pipeline/issues/6365) and [alpha propagated object params that has led to the unclear behaviour with opting in all alpha features together](https://github.com/tektoncd/pipeline/issues/5988). 
 
-- Cluster operators can't choose a default stability level for features that are not controlled by API fields.
-  - Some behavioral feature flags, such as `enforce-nonfalsifiability` has also been gated by `enable-api-fields`, but this forces cluster operators interested in these features to enable 2 flags for a single feature.
-  - Behavioral feature flags have not been gated by `enable-api-fields`. For these feature flags, cluster operators can't opt into a default stability level. For example, if a cluster operator wants to enable only `stable` features, and maintainers enable a behavioral feature by default when moving it to `beta`, the cluster operator needs to read release notes to be aware of the feature and disable it. 
+- Some behavioral feature flags can cause confusions due to the inconsistencies in how they are used with group feature flag. For example, the “enforce-nonfalsifiability” is a behavioral flag that has also been gated by “enable-api-fields”, but this forces cluster operators interested in these features to enable 2 flags for a single feature.
 
 ### Feature stability coupled to CRD API version
 
@@ -45,6 +43,8 @@ Per [TEP-0033](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-
 
 - For maintainers, the maintenance operation of swapping the storage version from v1beta1 to v1 should not have affected our users. However, we had to [change the user-facing default value of enable-api-fields from `stable` to `beta` ](https://github.com/tektoncd/pipeline/pull/6732) before changing the storage version of the API to [avoid breaking PipelineRuns using `beta` features](https://github.com/tektoncd/pipeline/pull/6444#issuecomment-1580926707).
 
+- When promoting features, it could cause confusions for contributors to be dependent on the fact whether an apiVersion is available. For example, during [the promotion to beta for projected workspaces](https://github.com/tektoncd/pipeline/pull/5530), the v1 api's existence led to confusions of what to do with beta features in v1beta1 and its difference with in v1.
+
 ## Goals
 
 - [Decouple API versioning and feature stability](https://github.com/tektoncd/pipeline/issues/6592)
@@ -57,6 +57,7 @@ Per [TEP-0033](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-
 - Minimize backwards incompatible changes and provide simple migration paths for cluster operators.
 - Cluster operators can set a default feature stability level.
   - For example, we want to address the current case where a cluster operator only wants to use `stable` features and we have defaulted `beta` as the opt-in features stability then they would have to change back the default feature stability to use all `stable` features by reading through the release notes.
+- Build consistency in the usage for the group feature flag and the behavioral feature flags.
 
 ## Non goals
 
@@ -67,4 +68,6 @@ Per [TEP-0033](https://github.com/tektoncd/community/blob/main/teps/0033-tekton-
   - [TEP-0085: Per-Namespace Feature Flags](https://github.com/tektoncd/community/blob/main/teps/0085-per-namespace-controller-configuration.md) is better suited to address this problem. This proposal focuses on the user experience of configuring the Tekton Pipelines features enabled in a Kubernetes cluster..
 - Ensure pending resources don't break with changing feature flags on downgrades or upgrades
   - As [handling backwards incompatible changes for pending resources](https://github.com/tektoncd/pipeline/issues/6479) pointed out, we have run into the cases where [feature flag info are changed or lost](https://github.com/tektoncd/pipeline/issues/5999) when handling deprecated fields which led the pending resources to break. However, this issue was introduced by the implementation of feature flags rather than its design, and can be addressed separately.
-  - Users can downgrade their pipeline versions without invalidating stored resources, even if stored resources cannot be run with the downgraded server. Keeping the stored resources valid relates with the storage migration instead of our feature flags implementations, which has been covered in [Storage version migrator v1beta1 -> v1](https://github.com/tektoncd/pipeline/issues/6667) and is out of scope.
+  - Users can downgrade their pipeline versions without invalidating stored resources, even if stored resources cannot be run with the downgraded server. Keeping the stored resources valid relates with the storage migration instead of our feature flags implementations, which has been covered in [Storage version migrator v1beta1 -> v1](https://github.com/tektoncd/pipeline/issues/6667) and is out of scope.
+- Strict control of behavioral flags for a specific stability level using a group flag
+  - The [review of the existing behavioral flags in Tekton Pipelines](https://docs.google.com/document/d/11F_UU2ZSQoDMci87sFxxJZeFJWXzaapZKLl_oT9M4BY) suggests that it is neither necessary nor possible to gate all behavioral features behind a certain stability level, as not all features gated by a behavioral flag are on the same stability level. For example, `coschedule` flag has four different values, two of which are ‘stable’ and two of which are ‘alpha’.

teps/README.md

@@ -125,3 +125,4 @@ This is the complete list of Tekton TEPs:
 |[TEP-0133](0133-configure-default-resolver.md) | Configure Default Resolver | implemented | 2023-03-21 |
 |[TEP-0134](0134-concise-pipelines.md) | Concise Pipelines | proposed | 2023-04-28 |
 |[TEP-0135](0135-coscheduling-pipelinerun-pods.md) | Coscheduling PipelineRun pods | implementable | 2023-06-22 |
+|[TEP-0138](0138-improve-tekton-pipeline-feature-flag.md) | Improve Tekton Pipeline Feature Flag | proposed | 2023-07-07 |