You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Related to elastic/kibana#221056 I think we should reconsider including that since detail in more contexts. For example, as stated in that Kibana issue:
if stability = stable, since should be mandatory and x-state should be "Generally available; added in xxx" where xxxx is the since value.
if stablility = experimental and since exists, x-state should be "Technical preview; added in xxxx` (or "Technical preview since xxx"). Otherwise it can just be "Technical preview".
if stability = beta and since exists, x-state should be "Beta; added xxxx" (or "Beta since xxx"). Otherwise it can continue to just be "Beta".
I think ideally since would be required in most scenarios. IMO since is not necessary in the Serverless-specific OpenAPI document, where only "Generally available", "Technical preview", and "Beta" are necessary (unless there is a need to start displaying date values in those cases). The exact terms for these lifecycle states should align with what is used in the narrative documentation frontmatter.
Motivation
This helps clarify situations where users are looking at the "main" branch of the documentation and can't tell when a new API was introduced (irrespective of its lifecycle state). The same can also occur once we have both 9.1.x and 9.0.x publishing on the "v9" branch of the documentation.
Currently that appears in both OpenAPI documents as follows:
"x-state": "Technical preview"
However, the proposed change would mean that the elasticsearch-serverless-openapi.json is unchanged but the elasticsearch-openapi.json should instead have:
"x-state": "Technical preview; added in 9.1.0"
The text was updated successfully, but these errors were encountered:
Uh oh!
There was an error while loading. Please reload this page.
🚀 Feature Proposal
Currently we support the
@availability
property as specified in https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md, including thesince
detail. However, we only output thesince
detail in the OpenAPI document whenstability
isstable
.Related to elastic/kibana#221056 I think we should reconsider including that
since
detail in more contexts. For example, as stated in that Kibana issue:stability
=stable
,since
should be mandatory andx-state
should be "Generally available; added in xxx" where xxxx is thesince
value.stablility
=experimental
andsince
exists,x-state
should be "Technical preview; added in xxxx` (or "Technical preview since xxx"). Otherwise it can just be "Technical preview".stability
=beta
andsince
exists,x-state
should be "Beta; added xxxx" (or "Beta since xxx"). Otherwise it can continue to just be "Beta".I think ideally
since
would be required in most scenarios. IMOsince
is not necessary in the Serverless-specific OpenAPI document, where only "Generally available", "Technical preview", and "Beta" are necessary (unless there is a need to start displaying date values in those cases). The exact terms for these lifecycle states should align with what is used in the narrative documentation frontmatter.Motivation
This helps clarify situations where users are looking at the "main" branch of the documentation and can't tell when a new API was introduced (irrespective of its lifecycle state). The same can also occur once we have both 9.1.x and 9.0.x publishing on the "v9" branch of the documentation.
Example
For example, GetQueryRequest.ts has the following specification:
Currently that appears in both OpenAPI documents as follows:
However, the proposed change would mean that the
elasticsearch-serverless-openapi.json
is unchanged but theelasticsearch-openapi.json
should instead have:The text was updated successfully, but these errors were encountered: