Set/update the feature status in the metadata for all features that are not stable

[johnma14]

Reference to this issue. Right now, the * is used pretty inconsistently through out the docs. There are some features that have the status set but haven't been updated to the current status or in some cases, experimental/alpha/stable features don't have the status set in the markdown.

E.g: JWT Claim based routing on the feature status page says it is Alpha but the status is set to Experimental Authorization Dry Run says it is Alpha but the status is set to Experimental

Question:

• Do we want to use * to mark all experimental/alpha/beta features or just experimental/alpha or just do not use it at all?

@craigbox @ericvn @howardjohn @kfaseela thoughts?

[johnma14]

Have some new contributors who can help with this.

[howardjohn]

Is there some way we can associate the features.yaml thing with these docs and make sure they are in sync?

[johnma14]

Can investigate that.

[craigbox]

Most everything in Istio is both "beta" and "production ready". (That's something I would choose to do differently but is largely aligned with Kubernetes.).

It seems like a good idea to (a) flag features that are not recommended for production (b) maintain this in one place. With an addition of a list of pages per feature to features.yaml, we could keep the status in sync.

I picked the first page I saw with a *, https://istio.io/latest/docs/tasks/extensibility/wasm-module-distribution/, which doesn't actually indicate anywhere on the page that the feature is alpha. That's an oversight which we could also automate around: a block displayed on each page with a status set pre-beta?

I don't know the difference between "experimental" and "alpha" any more. Is there a reason to disambiguate them, and to have experimental features documented? Are they not alpha by the stage they reach the docs?

[paddydoyle]

I've started looking at this issue with @johnma14 .

Aside: I just wanted to say as a (hopefully!) first-time contributor, it was really great to have https://istio.io/v1.17/docs/releases/contribute/review/ to explain the process. And then in particular, https://istio.io/v1.17/docs/releases/contribute/shortcodes/ answered some of my questions about 'boilerplate'.

Part 1 - manually sync up features.yaml maturity with the status flag in the doc pages

I'm working on a draft PR for this - I'll share it shortly.

One thing to call out is that there is a boilerplates/experimental.md, but no equivalent boilerplates/alpha.md. I think we should add one for consistency.

And re:

It seems like a good idea to (a) flag features that are not recommended for production

..I think we can do that by (manually) adding {{< boilerplate experimental >}} or {{< boilerplate alpha >}} to the top of the page. Does that seem reasonable?

Part 2 - add boilerplate to the Alpha/Experimental pages automatically

Instead of adding {{< boilerplate experimental >}} by hand, it would be better to use the page template to add it if the status field is set.

Am not quite sure how to do this one - is it the primary_top.html template that would need it?

Part 3 - automate the doc pages, based on maturity in features.yaml

This is for:

(b) maintain this in one place

Am not sure of an easy way to do that. I see that features.yaml is pulled from an upstream URL, which makes it a little trickier to manage. But more importantly I noticed that some of the features with the maturity set, do not have a link attribute.. which would make it impossible to know which index.md file to automatically update. This might deserve a separate issue?

[paddydoyle]

https://github.com/istio/istio.io/pull/12821 for Part 1

[craigbox]

Reopening, in case @paddydole wants to work on a part 2!