Product Configuration #1865

cotti · 2025-09-10T09:29:58Z

Handles #1637

This PR performs a few refactorings into how we deal with product, versioning and legacy URL mapping definitions.

Configuration

Substitutions have been added for products to access their labels.
Initialization for products.yml and legacy-url-mappings.yml occurs during early service bootstrapping.

Products Listing

We now have a products.yml file to gather essential product metadata. Currently, we have a friendly label for each, and reference the versioning system adopted by the project in question.

Versioning

Updated to leverage the connection between Product/Version/LegacyURL.

Legacy Url Mapping

legacy-url-mappings.yml has been reviewed to include a reference to a product. Most entries have a direct correlation. For a few cases, a best-match approach was taken.

Docs

Docs-builder's documentation was updated to reflect these changes.

…roduct metadata, and substitution support for them

…roducts.yml

# Conflicts: # config/legacy-url-mappings.yml # src/tooling/docs-assembler/Cli/RepositoryCommands.cs

reakaleek · 2025-09-10T09:33:49Z

config/legacy-url-mappings.yml

@@ -1,82 +1,228 @@
 #############################################
 # This file defines the legacy URL mappings for the documentation site.
 # It maps current documentation pages to older versions to ensure users can find the content they need.
-# TODO: Refactor the model, for now we just use the first element as current version
+# Upon creation of version selection dropdowns, this data is combined with the current version of its product.
 #############################################

 stack: &stack [ '9.0+', '8.19', '8.18', '8.17', '8.16', '8.15', '8.14', '8.13', '8.12', '8.11', '8.10', '8.9', '8.8', '8.7', '8.6', '8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.17' ]


Why is 9.0+ still here?

Question also applies to other legacy_versions.

Oh, that didn't go.

626c199

What about other legacy versions? E.g. apm agent rum also contains the current version. Others might too.

theletterf

@elastic/docs-engineering I think this PR would also solve #1497

What happens with existing product subs define in docset.yml files, by the way? Should we prefer products.yml driven substitutions from now on?

theletterf · 2025-09-10T09:48:45Z

docs/configure/site/products.md

@@ -0,0 +1,37 @@
+# `products.yml`
+
+The [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) file specifies metadata regarding the projects in the organization leveraging v3.


Suggested change

The [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) file specifies metadata regarding the projects in the organization leveraging v3.

The [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) file specifies metadata regarding the projects in the organization that use the V3 docs system.

"leveraging v3" doesn't say much. Could you apply the suggested edit? 🙏🏻

docs/configure/site/products.md

Mpdreamz

A few small nits and q's.

Would be good to include more tests on resolving product names and their attached versioning schemes.

Mpdreamz · 2025-09-10T09:47:18Z

docs/configure/site/products.md

+
+| Substitution | Result |
+| --- |---|
+| `{{ product.apm-agent-dotnet }}` |{{ product.apm-agent-dotnet }}   |


In a follow up it would be cool to be able to do a version muations on these e,g

{{ .apm-agent-ios | version }} and {{ .apm-agent-ios | version | M.M }} etcetera.

Mpdreamz · 2025-09-10T09:48:55Z

docs/syntax/version-variables.md

@@ -105,6 +107,17 @@ This is dictated by the [`versions.yml`](https://github.com/elastic/docs-builder
 * `edot_python`
 * `edot_cf_aws`
 * `edot_collector`
+* `apm_attacher`
+* `apm_lambda`
+* `ecs_logging_dotnet`


Should we use kebab-case for versioning schemes as well to match product keys?

I went the opposite way just now - We already have docs in other repos (opentelemetry for example) using lowercase. I did kebab first to follow the repo names closely. Kinda on the fence for that one.

yeah kebab-case feels more natural.

Can the parsing be lenient to camel_case but always emit kebab-case?

Mpdreamz · 2025-09-10T09:53:00Z

src/tooling/docs-assembler/AssembleSources.cs

@@ -42,7 +43,7 @@ public class AssembleSources

 	public FrozenDictionary<Uri, NavigationTocMapping> NavigationTocMappings { get; }

-	public FrozenDictionary<string, IReadOnlyCollection<string>> LegacyUrlMappings { get; }
+	public LegacyUrlMappingConfiguration LegacyUrlMappings { get; }


Good cleanup 👍

Mpdreamz · 2025-09-10T09:54:22Z

src/Elastic.Documentation.Configuration/Products/Product.cs

+	public VersioningSystem? VersioningSystem { get; init; }
+}
+
+public sealed class ProductEqualityComparer : IEqualityComparer<Product>, IComparer<Product>


Missing tests for this, Add a comment why we need custom equality and comparison checks for Product.

Mpdreamz · 2025-09-10T09:56:20Z

src/Elastic.Documentation.Configuration/ConfigurationFileProvider.cs

@@ -23,6 +26,10 @@ public partial class ConfigurationFileProvider
 	private readonly IFileSystem _fileSystem;
 	private readonly string _assemblyName;

+	internal IDeserializer Deserializer { get; } = new StaticDeserializerBuilder(new YamlStaticContext())


Should this use the DocsBuilderStaticContext as per https://github.com/elastic/docs-builder/pull/1865/files#diff-1cf450b2111680a6b66c82509cb42a43b384ae2a09c257b684aec2a28045e245R20

If so should we make this static and update the linked usage as well?

Co-authored-by: Fabrizio Ferri-Benedetti <[email protected]>

docs/configure/site/products.md

Fabrizio with the save. Co-authored-by: Fabrizio Ferri-Benedetti <[email protected]>

reakaleek · 2025-09-10T10:14:28Z

Smoke tests are failing. We should run a full assembler build to validate.

github-actions · 2025-09-10T14:36:41Z

🔍 Preview links for changed docs

…ture/product_config

…frontmatter definitions

florent-leborgne

I think we're adding possible confusion points in the products.yml file with duplicates or nearly duplicate entries. LMK what you think.

florent-leborgne · 2025-09-10T17:37:33Z

config/products.yml

+  self:
+    display: 'Elastic Stack'
+    versioning: 'stack'
+  serverless:


What's the difference with cloud_serverless? I think we only need one

florent-leborgne · 2025-09-10T17:42:03Z

config/products.yml

+  serverless_elasticsearch:
+    display: 'Elasticsearch'
+    versioning: 'all'
+  serverless_observability:
+    display: 'Elastic Observability'
+    versioning: 'all'
+  serverless_security:
+    display: 'Elastic Security'
+    versioning: 'all'


Can you clarify how these behave? They're the solutions, on serverless. We have keys for the solutions already a bit above.
In terms of products, Elastic Observability, Elastic Security, and Elasticsearch can have 'stack' and 'serverless' versioning.
Unless we want to treat them as separate products, in which case the display name for the Serverless ones should be "Elastic Observability Serverless" "Elastic Security Serverless" "Elasticsearch Serverless".

florent-leborgne · 2025-09-10T17:43:15Z

config/products.yml

+  self:
+    display: 'Elastic Stack'
+    versioning: 'stack'


Suggested change

self:

display: 'Elastic Stack'

versioning: 'stack'

self:

display: 'Self-managed Elastic'

versioning: 'stack'

I think this is more accurate and makes a better distinction with the 'stack' key.

cotti added 10 commits September 3, 2025 11:09

Introduce products.yml as the central resource to catalogue primary p…

39befc6

…roduct metadata, and substitution support for them

Adjust legacy URL mapping to use Product metadata

a2ebf39

Merge branch 'main' into feature/product_config

d663ede

Refactor legacy-url-mappings.yml, update values on versions.yml and p…

9521c8a

…roducts.yml

Merge branch 'main' into feature/product_config

752f80d

# Conflicts: # config/legacy-url-mappings.yml # src/tooling/docs-assembler/Cli/RepositoryCommands.cs

Fix merge

c9a7ec3

Refactor location of Product

d328e32

Fix property definition

6361eb1

Refactor loading Product and LegacyUrlMapping data

1ddfa3e

Add documentation

ed9aeb1

cotti self-assigned this Sep 10, 2025

cotti requested a review from a team as a code owner September 10, 2025 09:29

cotti added the feature label Sep 10, 2025

cotti requested review from a team as code owners September 10, 2025 09:29

cotti requested a review from Mpdreamz September 10, 2025 09:30

github-actions bot deployed to docs-preview September 10, 2025 09:30 View deployment

theletterf requested a review from colleenmcginnis September 10, 2025 09:36

reakaleek reviewed Sep 10, 2025

View reviewed changes

theletterf reviewed Sep 10, 2025

View reviewed changes

cotti added 2 commits September 10, 2025 06:54

Fix legacy version lists with 9.0+ entries

626c199

Standardize with underscores

806259e

Mpdreamz requested changes Sep 10, 2025

View reviewed changes

github-actions bot had a problem deploying to docs-preview September 10, 2025 09:57 Failure

Update docs/configure/site/products.md

0434e00

Co-authored-by: Fabrizio Ferri-Benedetti <[email protected]>

github-actions bot deployed to docs-preview September 10, 2025 10:00 View deployment

theletterf reviewed Sep 10, 2025

View reviewed changes

docs/configure/site/products.md Outdated Show resolved Hide resolved

Update docs/configure/site/products.md

d4a2167

Fabrizio with the save. Co-authored-by: Fabrizio Ferri-Benedetti <[email protected]>

github-actions bot deployed to docs-preview September 10, 2025 10:11 View deployment

cotti added 2 commits September 10, 2025 10:17

Merge branch 'main' into feature/product_config

ea83361

Merge branch 'main' into feature/product_config

bad491a

github-actions bot deployed to docs-preview September 10, 2025 14:04 View deployment

Merge branch 'main' into feature/product_config

b527459

github-actions bot deployed to docs-preview September 10, 2025 14:34 View deployment

cotti added 2 commits September 10, 2025 11:38

Merge remote-tracking branch 'origin/feature/product_config' into fea…

b6e1e51

…ture/product_config

Revert to kebab-case product definition and allow compatibility with …

03f3ccf

…frontmatter definitions

github-actions bot deployed to docs-preview September 10, 2025 15:17 View deployment

Fix lint

c0130e4

github-actions bot deployed to docs-preview September 10, 2025 15:24 View deployment

cotti added 2 commits September 10, 2025 12:44

Standardize on underscores as it is more widely used by writers

7ee832e

Merge branch 'main' into feature/product_config

9ba7cf7

github-actions bot deployed to docs-preview September 10, 2025 15:45 View deployment

florent-leborgne reviewed Sep 10, 2025

View reviewed changes

		@@ -0,0 +1,37 @@
		# `products.yml`

		The [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) file specifies metadata regarding the projects in the organization leveraging v3.

Product Configuration #1865

Are you sure you want to change the base?

Product Configuration #1865

Conversation

cotti commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Configuration

Products Listing

Versioning

Legacy Url Mapping

Docs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reakaleek Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Mpdreamz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

reakaleek commented Sep 10, 2025

Uh oh!

github-actions bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

florent-leborgne left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cotti commented Sep 10, 2025 •

edited

Loading

reakaleek Sep 10, 2025 •

edited

Loading

github-actions bot commented Sep 10, 2025 •

edited

Loading