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

config/legacy-url-mappings.yml

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?

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.

docs/configure/site/products.md

docs/syntax/version-variables.md

src/tooling/docs-assembler/AssembleSources.cs

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

src/Elastic.Documentation.Configuration/ConfigurationFileProvider.cs

Co-authored-by: Fabrizio Ferri-Benedetti <fabri.ferribenedetti@elastic.co>

docs/configure/site/products.md

Fabrizio with the save. Co-authored-by: Fabrizio Ferri-Benedetti <fabri.ferribenedetti@elastic.co>

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

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

shainaraskas · 2025-09-12T19:29:11Z

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

I share this confusion - can we maybe reference these in docset.yml so we can keep using the same variables?

shainaraskas

threw some comments on where I could. I suggested a couple of terminology fixes and version # fixes

I'd like to better understand how this actually impacts the functionality of the dropdown - maybe a quick demo could be helpful, or even just explaining using an image of the dropdown what info is populated from where. want to understand what is actually changing with the experience based on these changes

config/products.yml

shainaraskas · 2025-09-12T20:01:49Z

config/products.yml

+    display: 'Elasticsearch Curator'
+    versioning: 'curator'
+  ecs:
+    display: 'Elastic Common Schema (ECS)'


do we want brackets on these? @colleenmcginnis

It depends on how this value is being used. Recently @KOTungseth requested that we use Elastic Common Schema (ECS) as the page title (elastic/docs-content#2212).

config/products.yml

config/legacy-url-mappings.yml

shainaraskas · 2025-09-12T20:12:36Z

config/legacy-url-mappings.yml

+    product: elastic-agent
+    legacy_versions: *stack
+  en/ingest-overview/:
+    product: elasticsearch


not elasticsearch

I've changed these to elastic-stack for now. Which entry would be more suitable?

shainaraskas · 2025-09-12T20:12:42Z

config/legacy-url-mappings.yml

+    product: elasticsearch
+    legacy_versions: []
+  en/ingest/:
+    product: elasticsearch


not elasticsearch

config/legacy-url-mappings.yml

shainaraskas · 2025-09-12T20:13:14Z

config/legacy-url-mappings.yml

+    product: cloud-serverless
+    legacy_versions: []
+  en/starting-with-the-elasticsearch-platform-and-its-solutions/:
+    product: elasticsearch


not elasticsearch

# Conflicts: # config/versions.yml # src/Elastic.Markdown/HtmlWriter.cs

cotti · 2025-09-16T14:41:30Z

threw some comments on where I could. I suggested a couple of terminology fixes and version # fixes

I'd like to better understand how this actually impacts the functionality of the dropdown - maybe a quick demo could be helpful, or even just explaining using an image of the dropdown what info is populated from where. want to understand what is actually changing with the experience based on these changes

For now, the current behavior of the dropdown is maintained - we just have more information wired in to perform further adjustments later on. Usage is the same.

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

shainaraskas

this looks good for the products I have knowledge of now (without being able to see how the elements are integrated in practice)

flagged one thing from the dev docs area for search ui versioning

would suggest that someone from the other docs teams (ingest and dev particularly) do a pass at this for product names and versions

shainaraskas · 2025-09-18T15:56:40Z

config/legacy-url-mappings.yml

+    legacy_versions: []
+  en/search-ui/:
+    product: search-ui
+    legacy_versions: ['1.24.1', '1.24.0']


I think these docs were versionless so there would be no legacy versions. current version is for 1.24+

config/products.yml

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

colleenmcginnis · 2025-09-18T22:59:56Z

config/legacy-url-mappings.yml

+    legacy_versions: [ '0.x' ]
+  en/apm/agent/dotnet/:
+    product: apm-agent-dotnet
+    legacy_versions: [ '1.33.0' ]


I don't think there should be any legacy versions for APM .NET agent.

Suggested change

legacy_versions: [ '1.33.0' ]

legacy_versions: []

colleenmcginnis · 2025-09-18T23:12:45Z

config/legacy-url-mappings.yml

It's not clear if legacy_versions should include the latest version or not.

For example, when I build the docs locally using this branch, on the APM Go agent pages, I only see 0.5 in the version dropdown, but I would expect to see 1.x and 0.5.

Similarly, for Stack-versioned pages, I'm seeing the 8.x list start with 8.18 instead of 8.19.

After I get clarity, I'll need to request more updates on the ingest-related items in this file.

colleenmcginnis · 2025-09-18T23:15:44Z

config/products.yml

+  apm-agent-android:
+    display: 'APM Agent for Android'
+    versioning: 'apm_agent_android'


@theletterf should we remove this in favor of edot-android?

I don't know. It's the same in versions.yml. All new documents use edot_, but the old ones don't. I don't know if keeping this here is required for some backward compatible mechanism. Is it, @cotti?

Otherwise, I would just keep edot_android and edot_ios.

colleenmcginnis · 2025-09-18T23:15:58Z

config/products.yml

+  apm-agent-ios:
+    display: 'APM Agent for iOS'
+    versioning: 'apm_agent_ios'


@theletterf should we remove this in favor of edot-ios?

See https://github.com/elastic/docs-builder/pull/1865/files/23b7f4bbe22cb2d65d13fcf78b7513699a83363e#r2362069224

config/products.yml

colleenmcginnis · 2025-09-18T23:27:52Z

config/products.yml

+  edot-sdk:
+    display: 'Elastic Distribution of OpenTelemetry SDK'
+    versioning: 'stack'


@theletterf does this make sense as a product? It wouldn't have a single versioning system (stack). 🤔

Hmm, nope, it doesn't. Would this be the required edit?

Suggested change

edot-sdk:

display: 'Elastic Distribution of OpenTelemetry SDK'

versioning: 'stack'

edot-sdk:

display: 'Elastic Distribution of OpenTelemetry SDK'

versioning: 'all'

colleenmcginnis · 2025-09-18T23:30:17Z

config/products.yml

+    versioning: 'stack'
+  ess:
+    display: 'Elastic Cloud Hosted'
+    versioning: 'all'


Is all the same as unversioned?

Same question.

colleenmcginnis · 2025-09-18T23:31:33Z

config/products.yml

+  apm-agent:
+    display: 'APM Agent'
+    versioning: 'stack'


If we keep this and versioning: 'all' means unversioned, I wonder if we should use that since no APM Agent is Stack versioned. 🤔 cc @theletterf

Agreed — if adding all is indeed the right option to get a versionless product listed.

Suggested change

apm-agent:

display: 'APM Agent'

versioning: 'stack'

apm-agent:

display: 'APM Agent'

versioning: 'all'

docs/configure/site/products.md

docs/syntax/substitutions.md

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

theletterf · 2025-09-19T07:47:06Z

config/versions.yml

    base: 0.1
    current: 0.2.0
+
+  # Logging


@shainaraskas @colleenmcginnis We can add UpdateCLI automated version bumps for these, too, in a follow-up PR.

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

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

config/legacy-url-mappings.yml Outdated Show resolved Hide resolved

theletterf reviewed Sep 10, 2025

View reviewed changes

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

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

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 <fabri.ferribenedetti@elastic.co>

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 <fabri.ferribenedetti@elastic.co>

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

shainaraskas reviewed Sep 12, 2025

View reviewed changes

cotti added 3 commits September 15, 2025 06:27

Merge branch 'main' into feature/product_config

20670d2

Adjust configuration files

96fcc48

Merge branch 'main' into feature/product_config

f911b3e

# Conflicts: # config/versions.yml # src/Elastic.Markdown/HtmlWriter.cs

github-actions bot had a problem deploying to docs-preview September 16, 2025 14:33 Failure

Fix cloud_terraform versioning

820b8c2

github-actions bot deployed to docs-preview September 16, 2025 14:38 View deployment

Apply suggestions from code review

725e26f

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

github-actions bot deployed to docs-preview September 16, 2025 14:48 View deployment

Update product label

e481c9a

github-actions bot deployed to docs-preview September 16, 2025 17:37 View deployment

cotti added 2 commits September 17, 2025 11:27

Merge branch 'main' into feature/product_config

28fb0f2

Fix remaining items on legacy mapping

6eefee6

github-actions bot deployed to docs-preview September 17, 2025 14:29 View deployment

shainaraskas approved these changes Sep 18, 2025

View reviewed changes

Update config/products.yml

23b7f4b

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

github-actions bot deployed to docs-preview September 18, 2025 20:12 View deployment

colleenmcginnis reviewed Sep 18, 2025

View reviewed changes

theletterf and others added 3 commits September 19, 2025 09:44

Update config/products.yml

46fd80c

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

Update config/products.yml

f9f5841

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

Update config/products.yml

8eff8fe

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

github-actions bot had a problem deploying to docs-preview September 19, 2025 07:45 Failure

Update config/products.yml

6a35a78

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

github-actions bot had a problem deploying to docs-preview September 19, 2025 07:46 Failure

theletterf reviewed Sep 19, 2025

View reviewed changes

theletterf and others added 2 commits September 19, 2025 09:47

Update docs/configure/site/products.md

ab480bd

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

Update docs/syntax/substitutions.md

8838b07

Co-authored-by: Colleen McGinnis <colleen.mcginnis@elastic.co>

github-actions bot deployed to docs-preview September 19, 2025 07:50 View deployment

Product Configuration #1865

Are you sure you want to change the base?

Product Configuration #1865

Uh oh!

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!

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Mpdreamz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

reakaleek commented Sep 10, 2025

Uh oh!

shainaraskas commented Sep 12, 2025

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

cotti commented Sep 16, 2025

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

theletterf Sep 19, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cotti commented Sep 10, 2025 •

edited

Loading

theletterf Sep 19, 2025 •

edited

Loading