Open johnma14 opened 1 year ago
Have some new contributors who can help with this.
Is there some way we can associate the features.yaml thing with these docs and make sure they are in sync?
Can investigate that.
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?
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'.
maturity
with the status
flag in the doc pagesI'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?
boilerplate
to the Alpha/Experimental pages automaticallyInstead 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?
maturity
in features.yamlThis 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?
https://github.com/istio/istio.io/pull/12821 for Part 1
Reopening, in case @paddydole wants to work on a part 2!
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 toExperimental
Authorization Dry Run says it isAlpha
but the status is set toExperimental
Question:
*
to mark all experimental/alpha/beta features or just experimental/alpha or just do not use it at all?@craigbox @ericvn @howardjohn @kfaseela thoughts?