diff --git a/docs/reference/query-languages/esql/README.md b/docs/reference/query-languages/esql/README.md index 8e0d1a3835d4b..67613be559289 100644 --- a/docs/reference/query-languages/esql/README.md +++ b/docs/reference/query-languages/esql/README.md @@ -105,16 +105,95 @@ To help differentiate between the static and generated content, the generated co % This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it. ``` +## Version differentiation in Docs V3 + +> [!IMPORTANT] +> Starting with 9.0, we no longer publish separate documentation branches for every minor release (`9.0`, `9.1`, `9.2`, etc.). +> This means there won't be a different page for `9.1`, `9.2`, and so on. Instead, all changes landing in subsequent minor releases **will appear on the same page**. + +Because we now publish just one docs set off of the `main` branch, we use the [`applies_to` metadata](https://elastic.github.io/docs-builder/syntax/applies/) to differentiate features and their availability across different versions. This is a [cumulative approach](https://elastic.github.io/docs-builder/contribute/#cumulative-docs): instead of creating separate pages for each product and release, we update a **single page** with product- and version-specific details over time. + +`applies_to` allows us to clearly communicate when features are introduced, when they transition from preview to GA, and which versions support specific functionality. + +This metadata accepts a lifecycle and an optional version. + +### Functions and operators + +Use the `@FunctionAppliesTo` annotation within the `@FunctionInfo` annotation on function and operator classes to specify the lifecycle and version for functions and operators. + +For example, to indicate that a function is in technical preview and applies to version 9.0.0, you would use: + +```java +@FunctionInfo( + returnType = "boolean", + appliesTo = { + @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.0.0") + }, + ... +) +``` + +When a feature evolves from preview in `9.0` to GA in `9.2`, add a new entry alongside the existing preview entry and remove the `preview = true` boolean: + +```java +@FunctionInfo( + returnType = "boolean", + preview = false, // the preview boolean can be removed (or flipped to false) when the function becomes GA + appliesTo = { + @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.PREVIEW, version = "9.0.0"), + @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.2.0") + }, + ... +) +``` + +We updated [`DocsV3Support.java`](https://github.com/elastic/elasticsearch/blob/main/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java) to generate the `applies_to` metadata correctly for functions and operators. + +### Inline `applies_to` metadata + +Use [inline annotations](https://elastic.github.io/docs-builder/syntax/applies/#inline-annotations) to specify `applies_to` metadata in descriptions, parameter lists, etc. + +For example, the second item in this list is in technical preview as of version 9.2: + +```markdown +- Item 1 +- Item 2 {applies_to}`stack: preview 9.2.` +``` + +### Key rules + +1. **Use the `preview = true` boolean** for any tech preview feature - this is required for the Kibana inline docs + - **Remove `preview = true`** only when the feature becomes GA on serverless and is _definitely_ going GA in the next minor release +2. **Never delete `appliesTo` entries** - only add new ones as features evolve from preview to GA +3. **Use specific versions** (`9.0.0`, `9.1.0`) when known, or just `PREVIEW` without a version if timing is uncertain +4. **Add `applies_to` to examples** where necessary + +> [!IMPORTANT] +> We don't use `applies_to` in the legacy asciidoc system for 8.x and earlier versions. + +### Supported lifecycles + +- `PREVIEW` - Feature is in technical preview +- `GA` - Feature is generally available +- `DEPRECATED` - Feature is deprecated and will be removed in a future release +- `UNAVAILABLE` - Feature is not available in the current version, but may be available in future releases + +> [!NOTE] +> Unreleased version information is automatically sanitized in the docs build output. For example, say you specify `preview 9.3.0`: +> - Before `9.3.0` is released, the live documentation will display "Planned for a future release" instead of the specific version number. +> - This will be updated automatically when the version is released. + ## Tutorials ### Adding a new command When adding a new command, for example adding the `CHANGE_POINT` command, do the following: 1. Create a new file in the `_snippets/commands/layout` directory with the name of the command, for example `change_point.md`. -2. Add the content for the command to the file. See other files in this directory for examples. -3. Add the command to the list in `_snippets/lists/processing-commands.md`. -4. Add an include directive to the `commands/processing-commands.md` file to include the new command. -5. Add tested examples to the `_snippets/commands/examples` directory. See below for details. +2. Ensure to specify what versions the command applies to. See [Version differentiation in Docs V3](#version-differentiation-in-docs-v3) for details. [Example PR](https://github.com/elastic/elasticsearch/pull/130314/files#diff-0ab90b6202c5d9eeea75dc95a7cb71dc4d720230342718bff887816771a5a803R3-R6). +3. Add the content for the command to the file. See other files in this directory for examples. +4. Add the command to the list in `_snippets/lists/processing-commands.md`. +5. Add an include directive to the `commands/processing-commands.md` file to include the new command. +6. Add tested examples to the `_snippets/commands/examples` directory. See below for details. ### Adding examples to commands