Expanding the "applies to" frontmatter

[lcawl]

I think as we wrestle with "real" content we're discovering a need for more facets in the applies to frontmatter.

In particular, we need:

• A way to separate the product and its version (e.g. Elastic stack v9.0) from the deployment type (e.g. on-prem, serverless, cloud hosted, ECE, ECK, etc). The current usage of "stack" to represent both the Elastic Stack version and the self-managed/on-prem environment is proving to be unclear (since "Elastic Stack" also exists on cloud hosted, ECE, and ECK).
• Per deprecated and removed features #413, we need more nuance around the lifecycle details (i.e. when the behaviour described in the page first became available, whether it's experimental or deprecated, and when it was removed) since the page can span multiple stages of availability. Right now I think it can only display one of those stages per deployment type.

I think we'll also eventually need:

• A way to specify the versions for non-stack-versioning products (for example, this arose when I was looking at the ECS logging content set and might also arise for things like APM agent docs). We might be okay for now but will need to have a way to accommodate those divergent schemes eventually.
• Frontmatter that captures the specific project types within serverless (e.g. we have some features that are rolled out to only a subset of the features at a particular point in time). We can cover this in text for now but might be nice to enable filtering on this in the future.

For example, maybe this means updating like this:

applies to:
  <deployment>: [lifecycle] [version]
  <product>: [lifecycle] [version], [lifecycle] [version], ...

Which would enable us to have scenarios like this:

applies to: 
  stack: beta 9.0, ga 9.1.1, deprecated 9.5, removed 10.0
  ecs: 8.17+
 apm-dotnet: 1.x
 serverless: all
 on-prem: all
 cloud: all

(this is a nonsense combination, just to demonstrate the types of products that currently have different release cadences and schemes).

The tricky part will be communicating things that are availability (or unavailable) at different stages as things get rolled from serverless to on-prem, for example. Maybe the only way to cover that in the metadata is to nest the fields? For example:

applies to: 
 serverless:
    observability: beta 2025-02-02, ga 2025-03-03
    security: beta 2025-0303
 on-prem:
    stack: beta 9.0, ga 9.1.1, deprecated 9.5, removed 10.0
 cloud: all

Note that I don't think we necessarily have to show all this information at the top of the page (maybe some of the historic lifecycle information is not shown or is only shown in a less-obtrusive section at the bottom of the page). Or maybe it's eventually used for a custom filtered view.

[Mpdreamz]

The current applies directive follows the following diagram:

stack, ece, eck, hosted, serverless to model the deploy band on that diagram.

We also support the deploy suites (orange blocks) self and cloud to assign their respective deployment types in one go which we need to document.

Here the deploy type stack has a very clear defined meaning (maybe we rename it to elk?).

A way to separate the product and its version (e.g. Elastic stack v9.0) from the deployment type (e.g. on-prem, serverless, cloud hosted, ECE, ECK, etc). The current usage of "stack" to represent both the Elastic Stack version and the self-managed/on-prem environment is proving to be unclear (since "Elastic Stack" also exists on cloud hosted, ECE, and ECK).

In the context of that diagram and renewed nomenclature that statement is not true I think. Stack does not exist on cloud hosted, ece, and eck.

---

Per #413, we need more nuance around the lifecycle details (i.e. when the behaviour described in the page first became available, whether it's experimental or deprecated, and when it was removed) since the page can span multiple stages of availability. Right now I think it can only display one of those stages per deployment type.

I am not opposed but I think we need to lay out the rules a bit e.g

 stack: beta 9.0, ga 9.1.1, deprecated 9.5, removed 10.0

If something is deprecated in 9.5 do we really want to show when it went to beta/ga? This will bring along a lot of visual clutter.

If its removed 10.0 why are we still showing the documentation page/section all together?

 stack: beta 9.0, ga 9.1.1

Here do we really need to be showing when it went beta? If the feature is available we can just leave the ga 9.1.1 and if its available in all platforms we should remove the applies directive all together?

I am not seeing where this adds value to current documentation.

---

A way to specify the versions for non-stack-versioning products (for example, this arose when I was looking at the ECS logging content set and might also arise for things like APM agent docs). We might be okay for now but will need to have a way to accommodate those divergent schemes eventually.

Maybe we can simplify this?

applies:
   product: ga 1.0

If product is set its the only value that may be set. In that case we render the applies block without the deployment type e.g just

Availability: GA 1.0

That way we don't have to support all the products under the sun as yaml keywords.

[florent-leborgne]

In the context of that diagram and renewed nomenclature that statement is not true I think. Stack does not exist on cloud hosted, ece, and eck.

This diagram is not fully accurate, it's missing the fact that a user running ECK, ECE, or Cloud hosted can run Stack-versioned deployments. For example, with ECE 3.7, you can run 7.17 or 8.2 or 8.17 deployments, same on Cloud Hosted, same on ECK... And we need that nuance in our docs. For those reasons, stack can't be used just to mean "a self-managed cluster"

If something is deprecated in 9.5 do we really want to show when it went to beta/ga? This will bring along a lot of visual clutter.

The docs need to stay truthful for users that aren't on the latest version. So it's important that they know in which state the feature they're reading about was for the version they're currently running. e.g. If something was added in tech preview in 9.1, then became GA in 9.6, it's useful to them to know that the 9.2 version that they're running on only has a preview version of that feature. We're not documenting the latest, we're documenting "since 9.0".

[lcawl]

This was I think a good summary from Florent today:

"...At the end of the day all users need to know on any page is one of the following:

This page applies to

• Elastic Stack version X.x running on [any, ECE version Y.y, ECK version Z.z, ECH, your own premises]
• Elastic Cloud Serverless [for Elasticsearch, for Observability, for Security] project types
• ECE version Y.y, ECK version Z.z, ECH, your own premises
• Another product version U.u

Where:

• "version", "running on", and "project types" are always optional
• only Elastic Cloud Serverless can be combined with another tagging scheme [to be confirmed?]..."

Only other facet off the top of my head is the lifecycle (experimental/beta/deprecated, etc)

[Mpdreamz]

@lcawl @florent-leborgne and I had a quick sync and came up with a model that we can capture in yaml frontmatter:

Projection of the new facets highlighted in #478

We capture this in the following yaml format:

apply:
   stack:
      ece:
      eck:
      self:
      ess:
      
   serverless:
       elasticsearch:
       observability:
       security:


   product: 
   

NOTE:

• stack may be empty in which case we talk about ece eck and ess as products not deployment types.
• A new keyword apply and directive :::{apply}. This to simplify engineering and we can simply warn on the old syntax.