Applies_to: Expand versioning features

[cotti]

This PR provides a set of adjustments to the inner workings of versioning in the context of applies_to. This draft will be further updated with front-end changes, but badge-related changes can be checked independently.

It is part of #2135.

Problem description

Describing versions within applicability contains several quirks and limitations, such as:

• Lack of version range support: Authors can only specify single versions, making it difficult to document features that span multiple versions
• Patch-level badge overload: Showing full Major.Minor.Patch versions creates visual clutter, specially for more complex applicability scenarios
• Missing base version context: When no version is specified for versioned products, readers don't know they're viewing version-specific documentation (e.g., "Stack 9.0+")

Proposed changes

• Version Specification (VersionSpec)

A new VersionSpec class has been created. It builds on SemVersion, and supports the following versioning types:

• Greater than or equal to: x.x+ or x.x (default)
• Range (inclusive): x.x-y.y
• Exact version: =x.x

// Examples:
stack: ga 9.1          // 9.1+ (default behavior)
stack: ga 9.1+         // 9.1+ (explicit)
stack: preview 9.0-9.2 // Range
stack: beta =9.1       // Exact version only

2. Simplified Badge Display

• Badges now display Major.Minor versions only, regardless of patch specification:
  9.5.0, 9.5.1, 9.5.6 -> all display as 9.5 or 9.5+

3. Base Version Display

When no version is specified for versioned products, the base version is now shown:

Before: stack: ga -> Badge shows just "Stack"
After: stack: ga -> Badge shows "Stack│8.0+" (assuming base = 8.0)

Unversioned products continue to show no version.

4. Validation Rules

Implemented validation in ApplicableToYamlConverter:

• One version declaration per lifecycle
• Only one "greater than or equal" per entry is allowed
• Ranges must not have a minimum version larger than the maximum version
• Overlapping version ranges are not allowed

# Valid:
stack: ga 9.2+, beta 9.0-9.1
stack: ga 9.2, beta =9.1

# Invalid - throws a warning:
stack: ga 9.2+, beta 9.0+     # Multiple >=
stack: ga 9.2+, beta 9.0-9.2  # Overlapping ranges

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/applies.md
• docs/testing/req.md

[reakaleek]

There are two test cases that made me curious.

Otherwise, LGTM.

Nice work.

[reakaleek]

➕ thanks for fixing this and making it properly.

[reakaleek]

I'm wondering a bit why there are so many warnings. What's the reason we can't do this backwards compatible?

[florent-leborgne]

I think we could remove this line @elastic/docs-tech-leads @vishaangelova, do you think it's very valuable?

[shainaraskas]

+1

[florent-leborgne]

@elastic/docs-tech-leads @vishaangelova can you think of other ways to describe ECH? I think in this form it may be a little confusing, maybe some small tweak like this?

Suggested change

	Description: "<strong>Elastic Cloud Hosted</strong> is a deployment of the Elastic Stack that's hosted on Elastic Cloud.",
	Description: "<strong>Elastic Cloud Hosted</strong> lets you manage and configure your own deployments of the Elastic Stack, hosted on Elastic Cloud.",

[shainaraskas]

what is the confusion we're trying to solve for? is it the fact that ECH is versionless and stack is not?

any definition will cause a little confusion because the ECH label also gets applied to the elastic cloud context (just like the ECE label gets applied to the orchestrator context as well as the deployment context).

ultimately, a hosted deployment is just a deployment of the Elastic Stack that's hosted on Elastic Cloud., as originally stated in the definition, and it's elastic cloud that is doing the management and configuration, even though it does it a little differently for ech/serverless/ccm.

I personally would leave the original definition for now ... one thing i want to possibly address in the metadata refactor is separating ECH and Serverless from Elastic Cloud which might make this better

does this help?

Suggested change

	Description: "<strong>Elastic Cloud Hosted</strong> is a deployment of the Elastic Stack that's hosted on Elastic Cloud.",
	Description: "<strong>Elastic Cloud Hosted</strong> is a deployment of the versioned Elastic Stack that's hosted on Elastic Cloud.",

[florent-leborgne]

This is all very nice - There are a few fairly minor things I'm wondering about after testing - I captured those in https://docs.google.com/document/d/1SWPnaia5I7XL5QcyZ_NUDOgn07xB43SPHjTsUW6OFLY/edit?tab=t.0