Applies_to: Expand versioning features

docs/_snippets/applies_to-version.md

@@ -1,10 +1,65 @@
 `applies_to` accepts the following version formats:
 
-* `Major.Minor`
-* `Major.Minor.Patch`
+### Version specifiers
 
-Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format.
+You can use version specifiers to precisely control how versions are interpreted:
+
+| Specifier | Syntax | Description | Example |
+|-----------|--------|-------------|---------|
+| Greater than or equal (default) | `x.x` `x.x+` `x.x.x` `x.x.x+` | Feature available from this version onwards | `ga 9.2+` or `ga 9.2` |
+| Range (inclusive) | `x.x-y.y` `x.x.x-y.y.y` | Feature available only in this version range | `beta 9.0-9.1` |
+| Exact version | `=x.x` `=x.x.x` | Feature available only in this specific version | `preview =9.0` |
+
+Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor` format in badges.
+
+:::{note}
+The `+` suffix is optional for greater-than-or-equal syntax. Both `ga 9.2` and `ga 9.2+` have the same meaning.
+:::
+
+### Examples
+
+```yaml
+# Greater than or equal (feature available from 9.2 onwards)
+stack: ga 9.2
+stack: ga 9.2+
+
+# Range (feature was in beta from 9.0 to 9.1, then became GA)
+stack: ga 9.2+, beta 9.0-9.1
+
+# Exact version (feature was in preview only in 9.0)
+stack: ga 9.1+, preview =9.0
+```
+
+### Implicit version inference for multiple lifecycles {#implicit-version-inference}
+
+When you specify multiple lifecycles with simple versions (without explicit specifiers), the system automatically infers the version ranges:
+
+**Input:**
+```yaml
+stack: preview 9.0, alpha 9.1, beta 9.2, ga 9.4
+```
+
+**Interpreted as:**
+```yaml
+stack: preview =9.0, alpha =9.1, beta 9.2-9.3, ga 9.4+
+```
+
+The inference rules are:
+1. **Consecutive versions**: If a lifecycle is immediately followed by another in the next minor version, it's treated as an **exact version** (`=x.x`).
+2. **Non-consecutive versions**: If there's a gap between one lifecycle's version and the next lifecycle's version, it becomes a **range** from the start version to one version before the next lifecycle.
+3. **Last lifecycle**: The highest versioned lifecycle is always treated as **greater-than-or-equal** (`x.x+`).
+
+This makes it easy to document features that evolve through multiple lifecycle stages. For example, a feature that goes through preview → beta → GA can be written simply as:
+
+```yaml
+stack: preview 9.0, beta 9.1, ga 9.3
+```
+
+Which is automatically interpreted as:
+```yaml
+stack: preview =9.0, beta 9.1-9.2, ga 9.3+
+```
 
 :::{note}
-**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last.
+**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 9.1, beta 9.0, preview 8.18` will be displayed with the highest priority lifecycle and version first. Items without versions are sorted last.
 :::

docs/syntax/_snippets/inline-level-applies-examples.md

@@ -55,15 +55,15 @@ This example shows how to use directly a key from the second level of the `appli
 ::::{tab-item} Output
 
 - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0`
-- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0`
+- {applies_to}`edot_python: preview =1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta =1.0.0, ga 1.2.0`
 - {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0`
 
 ::::
 
 ::::{tab-item} Markdown
 ```markdown
 - {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0`
-- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0`
+- {applies_to}`edot_python: preview =1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta =1.0.0, ga 1.2.0`
 - {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0`
 ```
 ::::

docs/syntax/_snippets/multiple-lifecycle-states.md

@@ -1,12 +1,35 @@
-`applies_to` keys accept comma-separated values to specify lifecycle states for multiple product versions. For example:
+`applies_to` keys accept comma-separated values to specify lifecycle states for multiple product versions.
 
-* A feature is added in 9.1 as tech preview and becomes GA in 9.4: 
+When you specify multiple lifecycles with simple versions, the system automatically infers whether each version represents an exact version, a range, or an open-ended range. Refer to [Implicit version inference](/_snippets/applies_to-version.md#implicit-version-inference) for details.
+
+### Examples
+
+* A feature is added in 9.0 as tech preview and becomes GA in 9.1: 
+
+    ```yml
+    applies_to:
+      stack: preview 9.0, ga 9.1
+    ```
+
+    The preview is automatically interpreted as `=9.0` (exact), and GA as `9.1+` (open-ended).
+
+* A feature goes through multiple stages before becoming GA:
+
+    ```yml
+    applies_to:
+      stack: preview 9.0, beta 9.1, ga 9.3
+    ```
+
+    Interpreted as: `preview =9.0`, `beta 9.1-9.2`, `ga 9.3+`
+
+* A feature is unavailable for one version, beta for another, preview for a range, then GA:
 
     ```yml
     applies_to:
-      stack: preview 9.1, ga 9.4
+      stack: unavailable 9.0, beta 9.1, preview 9.2, ga 9.4
     ```
 
+    Interpreted as: `unavailable =9.0`, `beta =9.1`, `preview 9.2-9.3`, `ga 9.4+`
 
 * A feature is deprecated in ECE 4.0 and is removed in 4.8. At the same time, it has already been removed in {{ech}}:
 
@@ -15,4 +38,17 @@
       deployment:
         ece: deprecated 4.0, removed 4.8
         ess: removed
+    ```
+
+    The deprecated lifecycle is interpreted as `4.0-4.7` (range until removal).
+
+* Use explicit specifiers when you need precise control:
+
+    ```yml
+    applies_to:
+      # Explicit exact version
+      stack: preview =9.0, ga 9.1+
+
+      # Explicit range
+      stack: beta 9.0-9.1, ga 9.2+
     ```

docs/syntax/_snippets/versioned-lifecycle.md

@@ -7,6 +7,8 @@
     ---
     ```
 
+    This means the feature is available from version 9.3 onwards (equivalent to `ga 9.3+`).
+
 * When a change is introduced as preview or beta, use `preview` or `beta` as value for the corresponding key within the `applies_to`:
 
     ```
@@ -16,6 +18,28 @@
     ---
     ```
 
+* When a feature is available only in a specific version range, use the range syntax:
+
+    ```
+    ---
+    applies_to:
+      stack: beta 9.0-9.1, ga 9.2
+    ---
+    ```
+
+    This means the feature was in beta from 9.0 to 9.1, then became GA in 9.2+.
+
+* When a feature was in a specific lifecycle for exactly one version, use the exact syntax:
+
+    ```
+    ---
+    applies_to:
+      stack: preview =9.0, ga 9.1
+    ---
+    ```
+
+    This means the feature was in preview only in 9.0, then became GA in 9.1+.
+
 * When a change introduces a deprecation, use `deprecated` as value for the corresponding key within the `applies_to`:
 
     ```
@@ -33,4 +57,6 @@
     applies_to:
       stack: deprecated 9.1, removed 9.4
     ---
-    ```
+    ```
+
+    With the implicit version inference, this is interpreted as `deprecated 9.1-9.3, removed 9.4+`.

docs/syntax/applies.md

@@ -29,6 +29,41 @@ Where:
 - The lifecycle is mandatory.
 - The version is optional.
 
+### Version Syntax
+
+Versions can be specified using several formats to indicate different applicability scenarios:
+
+| Description | Syntax | Example | Badge Display |
+|:------------|:-------|:--------|:--------------|
+| **Greater than or equal to** (default) | `x.x+` `x.x` `x.x.x+` `x.x.x` | `ga 9.1` or `ga 9.1+` | `9.1+` |
+| **Range** (inclusive) | `x.x-y.y` `x.x.x-y.y.y` | `preview 9.0-9.2` | `9.0-9.2` or `9.0+`* |
+| **Exact version** | `=x.x` `=x.x.x` | `beta =9.1` | `9.1` |
+
+\* Range display depends on release status of the second version.
+
+**Important notes:**
+
+- Versions are always displayed as **Major.Minor** (e.g., `9.1`) in badges, regardless of whether you specify patch versions in the source.
+- Each version statement corresponds to the **latest patch** of the specified minor version (e.g., `9.1` represents 9.1.0, 9.1.1, 9.1.6, etc.).
+- When critical patch-level differences exist, use plain text descriptions alongside the badge rather than specifying patch versions.
+
+### Version Validation Rules
+
+The build process enforces the following validation rules:
+
+- **One version per lifecycle**: Each lifecycle (GA, Preview, Beta, etc.) can only have one version declaration.
+  - ✅ `stack: ga 9.2+, beta 9.0-9.1`
+  - ❌ `stack: ga 9.2, ga 9.3` 
+- **One "greater than" per key**: Only one lifecycle per product key can use the `+` (greater than or equal to) syntax.
+  - ✅ `stack: ga 9.2+, beta 9.0-9.1`
+  - ❌ `stack: ga 9.2+, beta 9.0+`
+- **Valid range order**: In ranges, the first version must be less than or equal to the second version.
+  - ✅ `stack: preview 9.0-9.2`
+  - ❌ `stack: preview 9.2-9.0`
+- **No version overlaps**: Versions for the same key cannot overlap (ranges are inclusive).
+  - ✅ `stack: ga 9.2+, beta 9.0-9.1`
+  - ❌ `stack: ga 9.2+, beta 9.0-9.2`
+
 ### Page level
 
 Page level annotations are added in the YAML frontmatter, starting with the `applies_to` key and following the [key-value reference](#key-value-reference). For example:
@@ -134,6 +169,22 @@ Use the following key-value reference to find the appropriate key and value for
 
 ## Examples
 
+### Version Syntax Examples
+
+The following table demonstrates the various version syntax options and their rendered output:
+
+| Source Syntax | Description | Badge Display | Notes |
+|:-------------|:------------|:--------------|:------|
+| `stack: ga 9.1` | Greater than or equal to 9.1 | `Stack│9.1+` | Default behavior, equivalent to `9.1+` |
+| `stack: ga 9.1+` | Explicit greater than or equal to | `Stack│9.1+` | Explicit `+` syntax |
+| `stack: preview 9.0-9.2` | Range from 9.0 to 9.2 (inclusive) | `Stack│Preview 9.0-9.2` | Shows range if 9.2.0 is released |
+| `stack: preview 9.0-9.3` | Range where end is unreleased | `Stack│Preview 9.0+` | Shows `+` if 9.3.0 is not released |
+| `stack: beta =9.1` | Exact version 9.1 only | `Stack│Beta 9.1` | No `+` symbol for exact versions |
+| `stack: ga 9.2+, beta 9.0-9.1` | Multiple lifecycles | `Stack│9.2+` | Only highest priority lifecycle shown |
+| `stack: ga 9.3, beta 9.1+` | Unreleased GA with Preview | `Stack│Beta 9.1+` | Shows Beta when GA unreleased with 2+ lifecycles |
+| `serverless: ga` | No version (base 99999) | `Serverless` | No version badge for unversioned products |
+| `deployment:`<br/>`  ece: ga 9.0+` | Nested deployment syntax | `ECE│9.0+` | Deployment products shown separately |
+
 ### Versioning examples
 
 Versioned products require a `version` tag to be used with the `lifecycle` tag:
@@ -240,22 +291,46 @@ applies_to:
 
 ## Look and feel
 
+### Version Syntax Demonstrations
+
+:::::{dropdown} New version syntax examples
+
+The following examples demonstrate the new version syntax capabilities:
+
+**Greater than or equal to:**
+- {applies_to}`stack: ga 9.1` (implicit `+`)
+- {applies_to}`stack: ga 9.1+` (explicit `+`)
+- {applies_to}`stack: preview 9.0+`
+
+**Ranges:**
+- {applies_to}`stack: preview 9.0-9.2` (range display when both released)
+- {applies_to}`stack: beta 9.1-9.3` (converts to `+` if end unreleased)
+
+**Exact versions:**
+- {applies_to}`stack: beta =9.1` (no `+` symbol)
+- {applies_to}`stack: deprecated =9.0`
+
+**Multiple lifecycles:**
+- {applies_to}`stack: ga 9.2+, beta 9.0-9.1` (shows highest priority)
+
+:::::
+
 ### Block
 
 :::::{dropdown} Block examples
 
 ```{applies_to}
-stack: preview 9.1
+stack: preview 9.1+
 serverless: ga
 
-apm_agent_dotnet: ga 1.0.0
-apm_agent_java: beta 1.0.0
-edot_dotnet: preview 1.0.0
+apm_agent_dotnet: ga 1.0+
+apm_agent_java: beta 1.0+
+edot_dotnet: preview 1.0+
 edot_python:
-edot_node: ga 1.0.0
-elasticsearch: preview 9.0.0
-security: removed 9.0.0
-observability: deprecated 9.0.0
+edot_node: ga 1.0+
+elasticsearch: preview 9.0+
+security: removed 9.0
+observability: deprecated 9.0+
 ```
 :::::