Add product features support on products.yml

[cotti]

This pull request introduces a new "features" system for products, allowing finer control over which subsystems each product participates in (such as release notes and public documentation). It enables products to be included in release notes without requiring them to be public documentation products, and updates the configuration, schema, and codebase to support this distinction. Documentation and validation logic are updated to explain and enforce the new behavior.

Features system for products

• Added a features mapping to product definitions in products.yml and documented it in products.md, allowing products to opt in to public-reference (public docs) and/or release-notes (changelog) features. Products with no features mapping participate in all subsystems for backward compatibility. [1] [2] [3]
• Updated the schema and validation logic so that only products with public-reference enabled can be used in documentation frontmatter or as page references; products with only release-notes enabled can appear in changelogs but not in docs. [1] [2] [3] [4]
• Updated changelog documentation to clarify that products with only the release-notes feature are valid for changelogs, and provided guidance for adding such products.

Codebase changes to support features

• Introduced the ProductFeatures type and updated the Product and ProductsConfiguration records to track feature participation, including a new PublicReferenceProducts collection for fast lookups. [1] [2] [3] [4]
• Updated YAML parsing and product lookup logic throughout the codebase to use the new PublicReferenceProducts collection where appropriate, ensuring only eligible products are used in documentation contexts. [1] [2] [3] [4]

Versioning system improvements

• Added a none versioning system to support products that only participate in release notes and do not have public documentation or versions. [1] [2]
• Updated product creation logic to assign the none versioning system to products that are not public-reference and have no explicit versioning.

Test and integration updates

• Updated test helpers and integration tests to initialize the new PublicReferenceProducts property in ProductsConfiguration. [1] [2] [3] [4] [5] [6] [7] [8]

Documentation updates

• Updated documentation to clarify the behavior of the new features system, including how substitutions and product references work, and added notes to help users configure products correctly for their intended use cases. [1] [2] [3] [4]

These changes make it possible to track internal tools and other non-public products in release notes without exposing them as documentation products, while maintaining backward compatibility for existing product definitions.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds per-product feature flags and a derived PublicReferenceProducts subset. Products may declare features.public-reference and/or features.release-notes; absence of features defaults to both enabled. Product creation resolves features, validates feature keys, and may assign VersioningSystem.None for products without public-reference. A PublicReferenceProducts frozen dictionary is exposed and used for substitution generation and frontmatter validation; changelog tooling and other consumers that need all products continue to use the full Products map. VersioningSystem.None and products YAML were updated accordingly.

Sequence Diagram(s)

sequenceDiagram
    participant FS as FileSystem (config files)
    participant ConfigBuilder as ConfigurationFile.CreateProducts
    participant ProductsConfig as ProductsConfiguration
    participant Substitutions as ConfigurationFile (substitutions)
    participant FrontMatter as ProductConverter / YamlSerialization
    participant Changelog as docs-builder changelog

    FS->>ConfigBuilder: read products.yml (with features)
    ConfigBuilder->>ProductsConfig: build Products map
    ConfigBuilder->>ProductsConfig: derive PublicReferenceProducts (filter public-reference)
    ProductsConfig->>Substitutions: provide PublicReferenceProducts
    Substitutions->>Substitutions: generate product.{id} substitutions only for PublicReferenceProducts
    ProductsConfig->>FrontMatter: provide PublicReferenceProducts
    FrontMatter->>FrontMatter: validate frontmatter product IDs against PublicReferenceProducts
    ProductsConfig->>Changelog: provide Products (all configured products)
    Changelog->>Changelog: allow changelog entries for any product (including release-notes-only)

Loading

Suggested labels

feature

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.90% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: introducing a features system for products in products.yml configuration.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the features system, codebase changes, versioning improvements, and documentation updates.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feature/product-features

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/Elastic.Documentation.Configuration/Products/ProductExtensions.cs`:
- Around line 25-27: When creating products in CreateProducts
(ProductExtensions.cs), detect when
ResolveVersioningSystem(versionsConfiguration, kvp.Value.Versioning ?? kvp.Key)
returns null while the product is marked as public-reference
(kvp.Value.PublicReference == true) and throw a descriptive exception to fail
fast; keep allowing a null versioning system for release-notes-only products
(e.g., kvp.Value.ReleaseNotesOnly == true) so those still accept null. Update
both places where VersioningSystem is set (the block using
ResolveVersioningSystem at the top and the similar block at lines ~46-49) to
perform this null-check after calling ResolveVersioningSystem and throw a clear
error referencing the product key when public-reference is enabled. Ensure the
exception message includes the product identifier (kvp.Key) and the
invalid/missing versioning value to aid debugging.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9a50b598-b075-49c7-974c-a01e100de1b8

📥 Commits

Reviewing files that changed from the base of the PR and between c4473c9 and f186f95.

📒 Files selected for processing (21)

• config/changelog.example.yml
• config/products.yml
• docs/configure/site/products.md
• docs/contribute/changelog.md
• docs/syntax/frontmatter.md
• src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs
• src/Elastic.Documentation.Configuration/Products/Product.cs
• src/Elastic.Documentation.Configuration/Products/ProductExtensions.cs
• src/Elastic.Markdown/Myst/FrontMatter/Products.cs
• src/Elastic.Markdown/Myst/YamlSerialization.cs
• tests-integration/Elastic.Assembler.IntegrationTests/TestHelpers.cs
• tests-integration/Mcp.Remote.IntegrationTests/McpToolsIntegrationTestsBase.cs
• tests/Elastic.ApiExplorer.Tests/TestHelpers.cs
• tests/Elastic.Changelog.Tests/Changelogs/ChangelogTestBase.cs
• tests/Elastic.Documentation.Build.Tests/TestHelpers.cs
• tests/Elastic.Documentation.Configuration.Tests/CrossLinkRegistryTests.cs
• tests/Elastic.Documentation.Configuration.Tests/DocumentInferrerServiceTests.cs
• tests/Elastic.Documentation.Configuration.Tests/ProductFeaturesTests.cs
• tests/Elastic.Documentation.Configuration.Tests/VersionInferenceTests.cs
• tests/Elastic.Markdown.Tests/TestHelpers.cs
• tests/authoring/Framework/Setup.fs

[coderabbitai]

♻️ Duplicate comments (1)

src/Elastic.Documentation.Configuration/Products/ProductExtensions.cs (1)

24-27: ⚠️ Potential issue | 🟠 Major

Fail fast when public-reference product has unresolved versioning

At Line 26, null versioning is only handled for non-public-reference products. Public-reference products can still be created with VersioningSystem = null, which defers failure to later paths.

Suggested fix

 				var features = ResolveFeatures(kvp.Key, kvp.Value.Features);
 				var versioningSystem = ResolveVersioningSystem(versionsConfiguration, kvp.Value.Versioning ?? kvp.Key);

-				if (versioningSystem is null && !features.PublicReference)
-					versioningSystem = VersioningSystem.None;
+				if (versioningSystem is null)
+				{
+					if (!features.PublicReference)
+						versioningSystem = VersioningSystem.None;
+					else
+						throw new InvalidOperationException(
+							$"Product '{kvp.Key}' has invalid or missing versioning '{kvp.Value.Versioning ?? kvp.Key}' while 'public-reference' is enabled."
+						);
+				}

As per coding guidelines, "Fail fast by throwing exceptions early rather than hiding errors."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/Elastic.Documentation.Configuration/Products/ProductExtensions.cs` around
lines 24 - 27, The code calls ResolveVersioningSystem(...) to populate
versioningSystem but only defaults null to VersioningSystem.None when
features.PublicReference is false; update the post-ResolveVersioningSystem check
so that if versioningSystem is null and features.PublicReference is true you
throw an exception (e.g., InvalidOperationException) with a clear message
including the product identifier (kvp.Key or kvp.Value.Name) to fail fast; keep
the existing branch that sets VersioningSystem.None when
features.PublicReference is false. Ensure this change is made in
ProductExtensions near the ResolveVersioningSystem(...) usage to prevent
creating public-reference products with unresolved versioning.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@src/Elastic.Documentation.Configuration/Products/ProductExtensions.cs`:
- Around line 24-27: The code calls ResolveVersioningSystem(...) to populate
versioningSystem but only defaults null to VersioningSystem.None when
features.PublicReference is false; update the post-ResolveVersioningSystem check
so that if versioningSystem is null and features.PublicReference is true you
throw an exception (e.g., InvalidOperationException) with a clear message
including the product identifier (kvp.Key or kvp.Value.Name) to fail fast; keep
the existing branch that sets VersioningSystem.None when
features.PublicReference is false. Ensure this change is made in
ProductExtensions near the ResolveVersioningSystem(...) usage to prevent
creating public-reference products with unresolved versioning.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 428f2b9c-f25b-4a6e-88ab-4318a4b85691

📥 Commits

Reviewing files that changed from the base of the PR and between f186f95 and 4d367e9.

📒 Files selected for processing (3)

• src/Elastic.Documentation.Configuration/Products/ProductExtensions.cs
• src/Elastic.Documentation.Configuration/Versions/VersionConfiguration.cs
• tests/Elastic.Documentation.Configuration.Tests/ProductFeaturesTests.cs

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/Elastic.Documentation.Configuration.Tests/ProductFeaturesTests.cs

[lcawl]

The doc updates LGTM!