RFC: Clarify stable features usage

[JeromeJu]

Changes

This commit helps clarify the usage of stable features to be apparent in also apis other than GA.

/kind documentation
part of: #6965

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has Docs if any changes are user facing, including updates to minimum requirements e.g. Kubernetes version bumps
• [n/a] Has Tests included if any functionality added or changed
• Follows the commit message standard
• [n/a] Meets the Tekton contributor standards (including functionality, content, code)
• Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
• [n/a] Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings). See some examples of good release notes.
• [n/a] Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

NONE

[tekton-robot]

@JeromeJu: The label(s) kind/doc cannot be applied, because the repository doesn't have them.

In response to this:

Changes

This commit helps clarify the usage of stable features to be apparent in also apis other than GA.

/kind doc

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has Docs if any changes are user facing, including updates to minimum requirements e.g. Kubernetes version bumps
• [n/a] Has Tests included if any functionality added or changed
• Follows the commit message standard
• [n/a] Meets the Tekton contributor standards (including functionality, content, code)
• Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
• [n/a] Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings). See some examples of good release notes.
• [n/a] Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

NONE

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[tekton-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign dibyom after the PR has been reviewed.
You can assign the PR to them by writing /assign @dibyom in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[tekton-robot]

@khrm: changing LGTM is restricted to collaborators

In response to this:

Thanks.

/lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[Yongxuanzhang]

/lgtm

[dibyom]

@JeromeJu one question I have is what does it mean for a feature to be GA when the API version is alpha 🤔

[JeromeJu]

@JeromeJu one question I have is what does it mean for a feature to be GA when the API version is alpha 🤔

Good point as I think this is also part of the issue TEP0138 is trying to address. I think we should find a way to elaborate that feature stability(versioning) shall be independent from API version. But not too sure if where this PR modifies is the place for such clarifications?

Maybe another section with a matrix of what each stability level mean in different api versions. WDYT?

[lbernick]

What's a bit confusing about this is right now we don't really have a notion of "stable features"-- it's just everything that's not an alpha or beta feature. I think this is why the question keeps coming up of why you'd describe fields of an alpha CRD as "stable". The way Kubernetes describes this is IMO a bit more clear: they talk about the feature lifecycle and explain that features "graduate" to GA after being beta, so a "stable" feature is a feature that has "graduated" from beta and no longer needs a feature gate. Similarly for us, a stable feature is something that was previously enabled by "enable-api-fields", but no longer is (although this isn't how I'd define a "stable" feature in user-facing docs). Maybe adopting some of Kubernetes' language around feature lifecycle could help clarify this confusion, especially if we move to per-feature flags. (Really it's just a different way of describing the same thing.)

Maybe another section with a matrix of what each stability level mean in different api versions. WDYT?

I'm concerned this will create more confusion related to people thinking the stability level of a feature is based on the stability level of the CRD it's present in.

[JeromeJu]

Maybe adopting some of Kubernetes' language around feature lifecycle could help clarify this confusion, especially if we move to per-feature flags. (Really it's just a different way of describing the same thing.)

That makes sense. I will open up another PR for this as introducing features lifecycle sounds like a somewhat related but different topic than api_compatibility_policy itself. I am not sure if a separate doc than this sounds better?

[lbernick]

A separate PR is totally fine; I think this doc is an appropriate place to describe feature lifecycle since it's very related to feature stability level. It might also be less confusing to wait until TEP 138 is resolved, especially if we do decide to adopt per-feature flags. Up to you!

[JeromeJu]

A separate PR is totally fine; I think this doc is an appropriate place to describe feature lifecycle since it's very related to feature stability level. It might also be less confusing to wait until TEP 138 is resolved, especially if we do decide to adopt per-feature flags. Up to you!

I agree that this could be one of the changes under TEP0138:) Let's wait till it gets merged.

[jerop]

/hold

tektoncd/community#1034 under discussion

[vdemeester]

@JeromeJu @jerop what is the status of this one ?

[JeromeJu]

@JeromeJu @jerop what is the status of this one ?

Thanks for the review, this has been made in #6941 PTAL! . Suggesting that we could close this:)

[vdemeester]

Alright, let's close it then.