Applies_to updates: allow version ranges and limit versions to Major.Minor

[florent-leborgne]

Followup to https://github.com/elastic/docs-content-internal/issues/343 and #1743
Also replaces #1709 due to the nature of the requested changes.

We're combining the range and patch simplification questions into 1 issue as we consider them to be very much related and shouldn't come at different times.

Challenge

• Only surfacing the version when a change was introduced doesn't lead to clear enough docs.
• A similar clarity challenge occurs with showing patch-level badges, especially because these changes are typically released in patches of several minor versions at the same time. This creates uncertainty on the authoring side as to how to document these changes using applies_to, and creates ambiguity as well as a badge overload in the published content. This challenge would also be overly complexified with the support of ranges.

Detailed proposals

To remediate these gaps, we need to:

• get the ability to input version ranges in applies_to and to show these ranges in badges and tooltips. The syntax to so should be simple and non-breaking to avoid any disruption.
• simplify the version part of applies_to by limiting them to Major.Minor and omit the patch part of it, and instead communicate and consider that each version-specific statement corresponds to the latest patch of said versions. To be clear, this means using a "9.5" badge for a change introduced in 9.5.0, 9.5.1, 9.5.6, etc. When absolutely critical to specify the patch version of a change, use a combination of "Major.Minor" badge and use plain text to describe the patch change ("9.2": Do this. If you're still using 9.2.1, do that.)

Find more context and information in these detailed docs:

• Ranges
• Patch handling simplification

Full specification for docs-eng

<In progress - Gdoc link to come>

Tasks

• Review and validate proposals with leads (✅ for Patches / WIP for Ranges)
• Build detailed specification for docs-eng <-- We're here
• Pre-implementation heads up to the docs-team
• Handoff to docs-eng
• Implementation on docs-eng side
• Content updates to match new implementation
  • Any changes required to accommodate ranges (make sure we haven't broken anything, and fix it if yes)
  • Any changes required to accommodate Patch simplification (make sure the content is still accurate)
• Update docs-builder docs
• Communicate to docs-team when changes are in effect

[theletterf]

The idea sounds very logical to me!

Are there situations where we'd want to convey messages like these?

• "This is compatible with "Product" up to version X.Y" (range with no start)
• "This is compatible with "Product" starting from X.Y" (range with no end — sort of implied currently, but not clear)

[theletterf]

Another rather embarrassing product situation we've faced is when something works in a version, then stops working for another, and then it's fixed or resumed. For example:

• Config added in 9.0
• Stops working in 9.1 or is different
• Works as in 9.0 again

Pretty niche...

[shainaraskas]

Are there situations where we'd want to convey messages like these?

"This is compatible with "Product" up to version X.Y" (range with no start)
"This is compatible with "Product" starting from X.Y" (range with no end — sort of implied currently, but not clear)

good callout. technically, our docs system reflects the functionality of a "base version" and later ... we've been debating indicating open-endedness (it likely worked this way in 8.x) vs. clearer signposts that this system only documents base++. I think we're leaning toward the latter because of the internal feedback we've received around "what version of the docs am I in??!?" @colleenmcginnis can correct me on that if I'm wrong.

Another rather embarrassing product situation we've faced is when something works in a version, then stops working for another, and then it's fixed or resumed. For example:

Config added in 9.0
Stops working in 9.1 or is different
Works as in 9.0 again

I think that we want to start documenting these as exceptions in the form of notes, or as bugs in our release notes. We've been considering doing the same for patch-level nuances we need to present when absolutely necessary.

In this system, you could also likely still use two separate applies tags, but I don't know if we want to codify that. Trying to balance guardrails vs. the necessary flexibility to let people say what they need to.

Do you think that we could see where we land with the implementation and then reassess if the system is really fighting us on explaining things in these cases?

[theletterf]

Do you think that we could see where we land with the implementation and then reassess if the system is really fighting us on explaining things in these cases?

I'm always for quick iterations and "Implement now, test later" :)

[shainaraskas]

@theletterf sry, was dumb and missed some nuance w your comment

"This is compatible with "Product" up to version X.Y" (range with no start)

prob we would do a 9.0-X.Y range to indicate that we know this was true in 9, but the cutoff is X.Y

"This is compatible with "Product" starting from X.Y" (range with no end — sort of implied currently, but not clear)

our x.x and x.x+ syntax covers this. the design assumes that when you add a value without an end date, or a value without indicating it's an exact version, you're saying "x.x and later". our ux improvements (adding a + to the badge, saying since x.x in the tooltip) will clarify this to readers.

[colleenmcginnis]

"This is compatible with "Product" up to version X.Y" (range with no start)

technically, our docs system reflects the functionality of a "base version" and later ... we've been debating indicating open-endedness (it likely worked this way in 8.x) vs. clearer signposts that this system only documents base++. I think we're leaning toward the latter because of the internal feedback we've received around "what version of the docs am I in??!?" @colleenmcginnis can correct me on that if I'm wrong.

Yes. In discussion with @florent-leborgne he said: I think that if we do this (say allow <9.1), we should still render this as 9.0-9.1. Because these are the v9 docs, not the v9 but sometimes v8 too, even though it is technically the case, it weakens the versioning model to leave this too open.

I agree with Florent (for example, if we say <9.1, does that imply it's relevant all the way back to 1.0?), but could be convinced otherwise if there's a strong case.