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?

[cotti]

@reakaleek The main factor is the decision to change the default behavior of a version assignment.

In short: x.x's old behavior should now be written as =x.x. x.x means x.x+.

Example: https://github.com/elastic/elasticsearch/blob/main/docs/reference/search-connectors/elastic-managed-connectors.md?plain=1 triggers two warnings. One regarding multiple applications using greater-than-or-equal syntax, and one about range overlap.

• {lifecycle} x.x is now implicitly lifecycle x.x+, but at the moment it is usually used throughout the docs to mean an exact, or up-until version.
• Since both unavailable and preview lifecycles use the old syntax, there are two ranges at work, and they eventually overlap.

[florent-leborgne]

Unavailable should never show a version - we may have missed this case in the specs; now that I think of it

If something is no longer in the product, we'd use "removed 8.0", with the removed lifecycle.
Unavailable strictly means that this is simply not possible to do with that product

[cotti]

Ah, that portion of the testing suite is still pending an update. I'll make sure the version doesn't show up in the final design.