versions.yml info

Author: shainaraskas

docs/contribute/_snippets/tag-processing.md

@@ -3,15 +3,19 @@
 Specifically for versioned products, badges will display differently when the `applies_to` key specifies a product version that has not been released to our customers yet.
 
 * `Planned` (if the lifecycle is preview, beta, or ga)
+  
+  Example: {applies_to}`stack: ga 99.99`
 * `Deprecation planned` (if the lifecycle is deprecated)
+  
+  Example: {applies_to}`stack: deprecated 99.99`
 * `Removal planned` (if the lifecycle is removed) 
 
-This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally.
+  Example: {applies_to}`stack: removed 99.99`
+
+This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally in [versions.yml](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation.Configuration/versions.yml).
 
 When multiple lifecycle statuses and versions are specified in the sources, several badges are shown.
 
 :::{note}
 Visuals and wording in the output documentation are subject to changes and optimizations.
-:::
-
-% todo: link to central config
+:::

docs/contribute/branching-strategy.md

@@ -62,6 +62,10 @@ Add an action as part of that repo’s release process for the release manager t
 
 When these releases happen, create a PR against the [assembler file](https://github.com/elastic/docs-builder/blob/main/src/tooling/docs-assembler/assembler.yml) that defines the new `current` branch, to merge on release day.
 
+:::{tip}
+Regardless of the branching strategy, you also need to update the current version in [versions.yml](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation.Configuration/versions.yml) as part of your release process. This version number is used in documentation variables and drives our [dynamic version badge logic](/contribute/cumulative-docs.md#how-do-these-tags-behave-in-the-output).
+:::
+
 
 ## Workflow 1 (default): Continuous deployment
 

docs/contribute/cumulative-docs.md

@@ -29,6 +29,12 @@ In order to achieve this, the markdown source files integrate a tagging system m
 
 This tagging system is mandatory for all of the public-facing documentation. We refer to it as “[applies_to](https://elastic.github.io/docs-builder/syntax/applies/)” tags or badges.
 
+## How version awareness works in Docs V3
+
+Docs V3 uses a central version config called [versions.yml](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation.Configuration/versions.yml), which tracks the latest released versions of our products. It also tracks the earliest version of each product documented in the Docs V3 system (the earliest available on elastic.co/docs). 
+
+This central version config is used in certain inline version variables, and drives our [dynamic rendering logic](#how-do-these-tags-behave-in-the-output). This logic allows us to label documentation related to unreleased versions as `planned`, continuously release documentation, and document our Serverless and {{stack}} offerings in one place.
+
 ## Tagging products and deployment models
 
 ### Page-level frontmatter (mandatory)
@@ -122,7 +128,12 @@ We do not do date-based tagging for unversioned products.
 ### For versioned products
 
 :::{include} /syntax/_snippets/versioned-lifecycle.md
-:::    
+::: 
+
+### Document features shared between serverless and {{stack}}
+
+:::{include} /syntax/_snippets/stack-serverless-lifecycle-example.md
+:::
 
 ### Identify multiple states for the same content  
 

docs/syntax/_snippets/stack-serverless-lifecycle-example.md

@@ -0,0 +1,21 @@
+If a change is released in Serverless and will be released in a future version of the {{stack}}, you can add both a `serverless` and `stack` tag, indicating the version of the {{stack}} in which the feature will be released:
+
+```
+---
+applies_to:
+  serverless: ga
+  stack: ga 9.2
+---
+```
+
+Because these changes need to be published as soon as the feature is released in Serverless, you might need to publish your docs before the feature is available in the {{stack}}. To allow for this, Docs V3 [displays badges differently](/contribute/cumulative-docs.md#how-do-these-tags-behave-in-the-output) when the `applies_to` tag specifies a product version that has not yet been released to customers.
+
+* A feature is tagged as available in a current Serverless release and a future {{stack}} version will render the following badges: 
+
+    {applies_to}`serverless: ga`
+    {applies_to}`stack: ga 99.99`
+
+* After the {{stack}} version is released, the same badges will render with the version number without any changes to the badge value in the source. 
+
+    {applies_to}`serverless: ga`
+    {applies_to}`stack: ga 9.0`