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?

[bmorelli25]

Sorry if I'm commenting on something that has already been decided.

I think ordering by product lifecycle is the wrong way to think about order.

In almost every example on your example page, the most recent version status is displayed at the top, and as you go down the list, you get to the least recent version. For example:

or

That pattern breaks in your deprecated in 9.2, removed in 9.5 example:

IMO, it's more useful to follow the previous pattern where the most recent version is always on the top of the list. To accomplish this, we'd either need to (1) adjust this product lifecycle order to something like:

{
		[ProductLifecycle.Removed] = new("Removed", "Removed", 0),
		[ProductLifecycle.Unavailable] = new("Unavailable", "Unavailable", 1),
		[ProductLifecycle.Deprecated] = new("Deprecated", "Deprecated", 2),
		[ProductLifecycle.Discontinued] = new("Discontinued", "Discontinued", 3),
		[ProductLifecycle.GenerallyAvailable] = new("GA", "Generally available", 4),
		[ProductLifecycle.Beta] = new("Beta", "Beta", 5),
		[ProductLifecycle.TechnicalPreview] = new("Preview", "Preview", 6),
		[ProductLifecycle.Development] = new("Development", "Development", 7),
		[ProductLifecycle.Planned] = new("Planned", "Planned", 8),
	};

OR (2), sort ordering of lifecycle states by version instead of product lifecycle.

I think option 2 is the correct option as it always ensures that the most recent information is at the top of the list.