Default enable-api-fields value for opt-in features once feature and API versioning are decoupled

[JeromeJu]

This issue tracks the decision to be made for the default enable-api-fields after decoupling the feature and api version. It has been discussed in the process of TEP0138 and is worth noted after the TEP being implemented. For context, we have changed the default enable-api-fields to beta for the v1 storage swap , and with decoupling the feature and api version, we would be able to switch back to stable enable-api-fields for any version upgrades.

Thanks to @lbernick and @afrittoli , there are couple of points to be discussed that are related:

• It is going to a backwards incompatible change to switch the default enable-api-fields to stable
  • Would it be worth it to make the breaking change?
  • What are we going to convey to users when we are making the change?
• What value are we going to have as the enable-api-fields in the long run?

/kind feature

[JeromeJu]

related:

• Decoupling API versioning and Feature versioning for features turned on by default #6592
• [TEP-0138]: Decouple API and Feature Versioning Proposal community#1034

[afrittoli]

Thanks @JeromeJu

I think we should try and switch to stable as default as soon as possible.
We have "alpha, beta and stable" path for our features to that as Tekton developers we can communicate to the users that we are working on certain features, users may try them, but we don't guarantee they won't change or even be descoped.
Enabling an alpha or beta feature should be a conscious choice, i.e. A user is keen on using a feature and is willing to take the risk that comes with it.

These are 5 features currently in beta, which are enabled by default in the v1beta1 API.

Feature	Proposal	Beta Release
Array Results and Array Indexing	TEP-0076	v0.45.0
Object Parameters and Results	TEP-0075	v0.46.0
Remote Tasks and Remote Pipelines	TEP-0060	v0.41.0
CSI workspaces	issue#4446	v0.41.0
Projected volume workspaces	issue#5075	v0.41.0

If we turned the api-feature-flag to stable by default, we would risk breaking users of these features who have not migrated to v1 yet.

I think the next steps could be:

• deprecate the current default value of the flag
• every alpha feature promoted to beta will be decoupled from the API version starting now
• wait until these 5 features are stable
• switch the default value back to stable

[JeromeJu]

Thank you Andrea for the investigations on the currently impacted beta features. I found csi and projected volume workspaces are documented to have become stable at tektoncd/community@d837715. I have been wondering if this would make sense as an example for other features that are currently at beta stability level now?

Also I opened #6954 to keep sync of the TEP096 and our codebase.

[lbernick]

chatted offline with @afrittoli and we came to the following conclusions:

• We should change all existing beta features to require enable-api-fields=beta regardless of api version now, and use this pattern for any new beta features.
• enable-api-fields should default to stable, for the reasons Andrea listed.

However, we are unsure of the best migration plan for getting enable-api-fields back to stable. Whenever we change enable-api-fields to stable, all beta features will go from enabled by default to disabled by default. Announcing it 9 months in advance gives cluster operators more time to adapt, but we don't know how many features will be in beta 9 months from now, so we don't know whether making this change in 9 months will result in more backwards incompatibility than making it at any other time. (We also don't want to stop new features from going to beta.)

To work around this, @afrittoli suggested a new flag, something like legacy-enable-beta-features-by-default, that we'd phase out after 9 months. We'd default enable-api-fields to stable and introduce this flag at the same time, with a default value of "true", preserving existing behavior. The main concern we have about this is that it could be confusing.

This chart would apply to the existing beta features (array results, array indexing, object params and results, and remote resolution):

enable-api-fields	legacy-enable-beta-features-by-default	enabled in v1beta1?	enabled in v1?
beta	true	yes	yes
beta	false	yes	yes
stable	true	yes	no
stable	false	no	no

This chart would apply to new beta features (e.g. probably matrix):

enable-api-fields	legacy-enable-beta-features-by-default	enabled in v1beta1?	enabled in v1?
beta	true	yes	yes
beta	false	yes	yes
stable	true	no	no
stable	false	no	no

We'd love to know what others think about how to address this problem!

[lbernick]

I've chatted with @jerop and @dibyom and will summarize our conversation here:

After writing up the table above, the three of us agree that another feature flag will add more complexity than necessary. We also all agree that the appropriate value for enable-api-fields is "stable".

Dibyo has suggested that instead of changing validation for v1beta1, we simply document that the updated validation will apply to future beta APIs, and swap "enable-api-fields" back to stable. The reason for this suggestion is that the user impact from the existing bug (v1beta1 pipelineruns being unable to create taskruns when "enable-api-fields" is set to "stable") is likely smaller than the user impact of turning off beta features by default for v1beta1, and the bug can be avoided (i.e. the pipelinerun fails during validation rather than at runtime) by migrating to v1.

[tekton-robot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

[vdemeester]

/remove-lifecycle stale
@JeromeJu what is the status for this ?

[JeromeJu]

Thanks for the reminder Vincent!

During WG we have reached consensus that the default enable-api-fields value will remain beta. This was made due to the following reasons:

• As of existing API-driven features under enable-api-fields, we are not switching back to stable for backwards-compatibility reason since changing back to stable might break users on those beta features.
• For new features, since we are having Per-feature flags, this would not be an issue since new features would only be enabled or disabled.

[JeromeJu]

Closing this as consensus has been reached and changes have been implemented.