Skip to content

Adds changes to the applies_to page #1325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 16 commits into
base: main
Choose a base branch
from

Conversation

charlotte-hoblik
Copy link

@charlotte-hoblik charlotte-hoblik commented May 30, 2025

Preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/1325/syntax/applies

Update applies_to page to match new versioning guidelines. Removed outdated parts and added missing info.

@charlotte-hoblik charlotte-hoblik self-assigned this May 30, 2025
@charlotte-hoblik charlotte-hoblik requested a review from a team as a code owner May 30, 2025 11:12
@charlotte-hoblik charlotte-hoblik added the documentation Improvements or additions to documentation label May 30, 2025
@charlotte-hoblik charlotte-hoblik marked this pull request as draft May 30, 2025 11:12
@charlotte-hoblik charlotte-hoblik marked this pull request as ready for review May 30, 2025 12:06
@charlotte-hoblik charlotte-hoblik changed the title Adds versioning changes to the applies_to page Adds changes to the applies_to page May 30, 2025
Copy link
Contributor

@leemthompo leemthompo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @charlotte-hoblik your changes about the updates look great, I just think we should take the opportunity to improve the overall structure of the page now that the information is more mature. I didn't give this a 100% thorough review, but should be enough to build upon your work.

security: unavailable
elasticsearch: beta
observability: deprecated
product: preview 9.5, deprecated 9.7
---

# Applies to
Copy link
Contributor

@leemthompo leemthompo May 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can restructure the page now that we have more info and have more logical progression:

Something like:

  1. Intro
  2. Syntax
  3. When and where to use applies_to ← new grouped section
  • Intro/explain that each level has slightly different syntax.
  • Mention stuff currently in 'when to use'
  • Levels:
    • Page-level (required)
    • Section-level
    • Inline
  1. Structured model (Maybe could have better heading name like "Metadata structure" or something)
  2. Examples

I'm not married to any specific ordering here apart from having more context and explanations up top. :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and maybe we can weave examples into other sections and remove the standalone examples #maybe

Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
@leemthompo
Copy link
Contributor

@charlotte-hoblik I think we could improve the flow in the Syntax section, namely by moving lifecycle up higher:

  • Basic pattern
  • Life cycle
  • Version
  • Combined states

Co-authored-by: Liam Thompson <[email protected]>
charlotte-hoblik and others added 2 commits June 2, 2025 15:08
Co-authored-by: Liam Thompson <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>
@charlotte-hoblik
Copy link
Author

charlotte-hoblik commented Jun 3, 2025

Thank you, @leemthompo for the helpful feedback and suggestions!
Heads-up: the examples are still a work in progress, with more updates coming.

Copy link
Contributor

@florent-leborgne florent-leborgne left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you thank you @charlotte-hoblik
Your changes already make this page so much better. 🙇

I'm leaving some comments that are mostly small clarifications or suggestions to add more overall context to the core purpose of these applies_to tag.

* `unavailable`
* `ga`

#### Version
Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd remove this sentence.

Unless I've missed a recent development, all products need a lifecycle tag. If a product key is entered without a value, it is not displayed in the output. For example: serverless: ga will show a serverless badge. While serverless: will show nothing.

I believe that what you're trying to say here, you are already saying it correctly later in this document when talking about unversioned products:

* When a change is released in ga, it **doesn’t need any specific tagging**.

stack: beta all
serverless: beta
```
✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments.
✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when availability differs across deployments and environments.

Really like those do/don'ts. I'd move them after the itemized list so we start with explanations on page/section/inline level. We can maybe have some more as well to help clarify some assumptions:

"""
Not every case requires an applies_to tag:
✅ Use applies_to tags to indicate which product or deployment type content applies to. This is mandatory for every page
❌ You don't need to tag every section or paragraph. Only do if the context or applicability changes from what has been established before
✅ Use applies_to tags when features change state in a specific update or release
❌ if the product is not versioned (meaning that all users are always on the latest version like serverless or cloud), you do not need to tag a new GA feature
❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes.
"""

^^ Just examples, I'm not precious about those.

# Applies to

Allows you to annotate a page or section's applicability.
The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release.
Starting with Elastic Stack version 9.0, ECE 4.0, and ECK 3.0, documentation is organized around user goals instead of per product, and each page stays valid over time and incorporates version-specific changes directly within the content using a [cumulative approach](../contribute/index.md#cumulative-docs).
That means that instead of creating separate pages for each product and release, we update the same page with product-specific and version-specific details.
In order to achieve this in a standardized way, the markdown source files integrate a **tagging system** meant to identify:
* Which Elastic products and deployment models the content applies to.
* When a feature goes into a new state as compared to the established base version.
This is what the `applies_to` metadata is for.

Borrowed and adjusted from #1324
I reckon that's a bit long as an intro, feel free to try to shorten :D

```

`all` can also be specified at a version level
## When and where to use `applies_to`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would move this section (until ### Lifecycle examples) just after the intro, before Syntax.
And add an ## Examples just before ### Lifecycle examples

Co-authored-by: florent-leborgne <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants