Skip to content

Conversation

tengqm
Copy link
Contributor

@tengqm tengqm commented Oct 5, 2025

This PR is about an English site-wide fix to feature gate references.
We are still referencing some feature gates that have been removed.
The removal of a feature gate is a strong indicator that the relevant feature won't get changed in the near future unless some serious bugs are reported.
We don't want to unnecessarily remind user that a feature is stable.
A reminder of this kind only triggers a suspicion that something is not so "stable".
A "stable" feature doesn't needs to be reminded forever.
References to a feature gate that has been removed is a source of confusion to users.

@k8s-ci-robot k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 5, 2025
@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign sayakmukhopadhyay for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

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

@k8s-ci-robot k8s-ci-robot added language/en Issues or PRs related to English language size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Oct 5, 2025
Copy link

netlify bot commented Oct 5, 2025

Pull request preview available for checking

Name Link
🔨 Latest commit 1c7ef72
🔍 Latest deploy log https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/68e25bb256799a0008b79500
😎 Deploy Preview https://deploy-preview-52626--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@tengqm tengqm force-pushed the fix-ref-gates-134 branch from 7a78128 to 1c7ef72 Compare October 5, 2025 11:51
@lmktfy
Copy link
Contributor

lmktfy commented Oct 5, 2025

This makes sense.

I changed my mind.

We can, and I think we, should, change the feature gate shortcode.

For example, for a removed feature gate, we can present a simple phrase
"This behavior has been stable since Kubernetes v1.xx".

I will open a PR to do that. I'm afraid I think it remains valuable to tell people when the feature went stable.

@lmktfy
Copy link
Contributor

lmktfy commented Oct 5, 2025

I opened #52632 to show how I'd address this. I genuinely hope people like the idea.

@tengqm
Copy link
Contributor Author

tengqm commented Oct 7, 2025

I don't think keeping the feature-state shortcode in a page is a sustainable approach. This is especially true for features that have been removed for several years. Considering that we cannot afford to distinguish "gates removed long ago" from "gates removed last year", stale feature-gate shortcode will make the pages more and more confusing.

We can, for sure, add lengthy texts to articulate the difference between a GA'ed feature and a removed feature, and we can add more texts to differentiate "locked" ones from others. However, the added texts are not helping users in a meaningful way. They only lead to more confusion.

I insist that we should add feature-state shortcode only when the relevant feature is still "usable". By "usable", I mean that adding a feature to the --feature-gates command line option won't break my cluster. This is a bottom line. Reading a page or a section saying that a feature is gated by Foo and it has been stable since v1.11 is not so helpful. People will get annoyed when they eventually find out that the Foo gate is not recognizable now. People will feel that the page has not been updated for years. People start losing trusts on the official documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. language/en Issues or PRs related to English language size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants