Applies_to: Allow no lifecycle and don't infer default when not set

[florent-leborgne]

We're giving too much importance to "GA" in our current lifecycles. GA is important when a feature evolves: from beta/preview to GA, or from GA to deprecated/removed.

In all other cases, it's not that important and when we do use applies_to the focus is rather on versions or deployment types rather than on their specific status.

The fact that we put GA everywhere or consider it the default is leading to wording issues and confusing statements in our docs.
Let's take a common example:

Here, we can see that the message:

• explains what stack is
• jump to "this is the status of this feature for these versions"

That's not the right angle.

The main meaning of this applies_to is: This specific piece of content applies to 9.4+

• The lifecycle doesn't matter because the functionality has no specific status, and if it had a specific status it should be an extra information, not the main one

With this in mind, I'm proposing to not infer GA by default, and to revise the wording for when GA is not explicitly set, as well as when it is probably.

This task would also include cleaning up our current applies_to in the source.

To be completed, it would be a joint effort between the writing team (defining the messaging udpates, cleaning up the content files) and docs-eng (updating the logic)

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

applies_to over-emphasizes "GA": the system infers GenerallyAvailable whenever a lifecycle is omitted, so a content author can't say "this just applies to 9.4+" without the reader-facing UI asserting a status ("Generally available since 9.4") that often isn't the point.

Findings

• src/Elastic.Documentation/AppliesTo/ProductLifecycle.cs:L9-L43 — the lifecycle enum has no "unset/none" member. GenerallyAvailable (L21-L22) is the only non-pre-release "available" state, so the model literally cannot represent "applies, lifecycle unspecified" as distinct from GA.
• src/Elastic.Documentation/AppliesTo/Applicability.cs:L22-L26 and :L242-L246 — both AppliesCollection.TryParse and Applicability.TryParse collapse empty / whitespace / all straight into GenerallyAvailable. This is the same GA-collapse flagged during Applies_to: Change default lifecycle to "Available" rather than "Generally Available" #2629 triage.
• src/Elastic.Documentation/AppliesTo/Applicability.cs:L151-L152, L176-L180 — the GenerallyAvailable singletons used as that default.
• src/Elastic.Markdown/Myst/AppliesTo/ApplicableToYamlConverter.cs:L342-L343 — at the YAML layer, a bare stack: (null/empty value) is assigned AppliesCollection.GenerallyAvailable; serverless:/deployment: empty similarly resolve to .All (L197-L198, L152-L153). So author intent "no lifecycle" is unreachable.
• src/Elastic.Documentation/AppliesTo/Applicability.cs:L255-L280 — the first token is always parsed as a lifecycle keyword, so a version-only entry like stack: 9.4 errors with "Unknown product lifecycle"; authors are forced to write ga 9.4.
• src/Elastic.Markdown/Myst/Components/ApplicabilityRenderer.cs:L220, L227 + LifecycleDescriptions.cs:L58-L59 + ProductLifecycleInfo.cs:L51 — this is the reader-visible symptom in the screenshot: popover text is built as "Generally available since {version}" and the GA description is "This functionality is generally available and ready for production usage." Note the badge already suppresses the GA label (ApplicabilityRenderer.cs:L121, Lifecycle != GenerallyAvailable) and shows just the version — so the gap is mainly the popover wording and the underlying default, not the badge.

Verdict

Needs stakeholder input

The request is not implemented and is not a quick fix. Delivering it means a data-model change (introduce a representation for "no lifecycle" so unset is distinguishable from GA, and stop inferring GA at the three sites above), a reader-visible wording change (what the popover says when no lifecycle is set), product/terminology decisions (is "no status" a first-class concept; what's the default messaging), and a source-content cleanup pass — exactly the joint writing + docs-eng effort the issue describes. It is tightly coupled to #2629 (default lifecycle "Available" vs "Generally available"): both touch the same GA-collapse and should be decided together to avoid contradictory models.

Proposal

Open questions, grouped by audience:

• Product — Should "applies to these versions, no lifecycle status" be a first-class, supported state (vs. always having some status)? When no lifecycle is set, what should the default reader message convey — pure version scope ("Available in 9.4+") with no status claim, or something else? Does this change deprecation/versioning policy semantics?
• Writer — Preferred authoring syntax for the no-lifecycle case (allow version-only stack: 9.4? a none keyword? bare stack: meaning "applies, no status"?). What migration story for the large body of existing applies_to that currently relies on the implicit-GA default — silent reinterpretation vs. a one-time cleanup? This is the content-cleanup half of the issue.
• Eng — How to model "unset" without breaking AOT JSON/YAML round-trips (ApplicableToJsonConverter, link-index serialization) and the cross-repo link contract; whether to add an enum member vs. a nullable lifecycle; coordinate with Applies_to: Change default lifecycle to "Available" rather than "Generally Available" #2629 so the two don't introduce competing defaults.

Related issues

Part of the applies_to / cumulative_docs cluster:

• Applies_to: Change default lifecycle to "Available" rather than "Generally Available" #2629 (open) — change default lifecycle to "Available" vs "Generally available". Direct sibling; same GA-collapse, should be decided jointly with this one.
• Applies_to: Allow a “ga&deprecated” special lifecycle status #2631 (open) — allow a combined ga&deprecated lifecycle status. Same lifecycle-model area.
• [Feature Request]: Throw error when version is invalid in applies_to #2094 (open) — error on invalid applies_to version; [Feature Request]: Improve error messages for applies-to problems #3009 (open) — improve applies_to error messages; invalid applies_to keys can be set in front matter #610 (open) — invalid applies_to keys accepted. Adjacent parser/validation work.

A maintainer may want to plan #3360 + #2629 (+ #2631) as one coherent lifecycle-model change.

Notes

• The current implicit-GA model traces to the versioning expansion in Applies_to: Expand versioning features #2322. Not a regression — working as originally designed.
• Labels applied: ai-triaged, ai:product-question, ai:writer-question, ai:eng-question.