Add product features support on products.yml (#3043)

* Add features mapping to products.yml

* Add docs-builder to products.yml for release notes

* Add tests

* Introduce VersioningSystem.None for products outside the public documentation cycle

* Set sentinel non-value for None

* Throw if there is no valid versioning for a product with public-reference enabled

Author: cotti

config/changelog.example.yml

@@ -19,7 +19,8 @@
 filename: timestamp
 
 # Products configuration (optional)
-# If not specified, all products from products.yml are allowed
+# If not specified, all products from products.yml are allowed (including those
+# that have 'public-reference' disabled).
 products:
   # List of available product IDs (empty = all from products.yml)
   # Accepts string or list: "elasticsearch, kibana" or [elasticsearch, kibana]

config/products.yml

@@ -59,6 +59,11 @@ products:
     versioning: 'terraform-google-edot-cf'
   curator:
     display: 'Elasticsearch Curator'
+  docs-builder:
+    display: 'Elastic Docs Builder'
+    repository: 'docs-builder'
+    features:
+      public-reference: false
   ecs:
     display: 'Elastic Common Schema (ECS)'
   ecs-logging:

docs/configure/site/products.md

@@ -11,6 +11,11 @@ products:
     display: 'Elastic Distribution of OpenTelemetry Collector'
     versioning: 'stack'
     repository: 'elastic-edot-collector'
+  docs-builder:
+    display: 'Elastic Docs Builder'
+    repository: 'docs-builder'
+    features:
+      public-reference: false
 #...
 ```
 
@@ -19,14 +24,19 @@ products:
 `products`
 :   A YAML mapping where each key is an Elastic product.
 * `display`: A friendly name for the product.
-* `versioning`: The versioning system used by the project. The value for this field must match one of the versioning systems defined in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml)
+* `versioning`: The versioning system used by the project. The value for this field must match one of the versioning systems defined in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml). Optional for products that only participate in release notes.
 * `repository`: The repository name for the product. It's optional and primarily intended for handling edge cases where there is a mismatch between the repository name and the product identifier.
+* `features`: An optional mapping that controls which docs-builder subsystems the product participates in. When omitted, all features are enabled (backward compatible). When present, all features default to `true` and individual features can be opted out by setting them to `false`. The available features are:
+  * `public-reference`: The product can be referenced in `applies_to` blocks, page frontmatter `products`, and gets `{{ product.<id> }}` substitutions. This is what "being a documentation product" means today.
+  * `release-notes`: The product participates in the changelog and release notes system.
 
-
+:::{note}
+Products without a `features` mapping behave exactly as before -- they participate in all subsystems. The `features` mapping uses opt-out semantics: all features are enabled by default, and you only need to set a feature to `false` to disable it. For example, internal tools that need release notes but don't have public-facing documentation can set `public-reference: false`.
+:::
 
 ## Substitutions
 
-Writing `{{ product.<product-id> }}` renders the friendly name of the product in the documentation. For example:
+Writing `{{ product.<product-id> }}` renders the friendly name of the product in the documentation. Substitutions are generated only for products with the `public-reference` feature (or no explicit `features` mapping). For example:
 
 | Substitution                    | Result |
 |---------------------------------|---|

docs/contribute/changelog.md

@@ -10,4 +10,4 @@ To use the `docs-builder changelog` commands in your development workflow:
 1. [Bundle changelogs](/contribute/bundle-changelogs.md) with the `docs-builder changelog bundle` command. For example, create a bundle for the pull requests that are included in a product release. When changelogs are no longer needed in the repo, [remove changelog files](/contribute/bundle-changelogs.md#changelog-remove) with `docs-builder changelog remove`.
 1. [Publish release notes](/contribute/publish-changelogs.md): Use the `{changelog}` directive in docs or `docs-builder changelog render` to produce release documentation.
 
-For more information about running `docs-builder`, go to [Contribute locally](https://www.elastic.co/docs/contribute-docs/locally).
+For more information about running `docs-builder`, go to [Contribute locally](https://www.elastic.co/docs/contribute-docs/locally).

docs/contribute/configure-changelogs.md

@@ -2,7 +2,7 @@
 
 Before you can use the `docs-builder changelog` commands in your development workflow, you must make some decisions and do some setup steps:
 
-1. Ensure that your products exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
+1. Ensure that your products exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). Products that only need release notes (not public documentation) can be added with `features: { public-reference: false }`. For more information, refer to [Products](/configure/site/products.md).
 1. Add labels to your GitHub pull requests that map to [changelog types](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs). At a minimum, create labels for the `feature`, `bug-fix`, and `breaking-change` types.
 1. Optional: Choose areas or components that your changes affect and add labels to your GitHub pull requests (such as `:Analytics/Aggregations`).
 1. Optional: Add labels to your GitHub pull requests to indicate that they are not notable and should not generate changelogs. For example, `non-issue` or `release_notes:skip`. Alternatively, you can assume that all PRs are *not* notable unless a specific label is present (for example, `@Public`).

docs/contribute/create-changelogs.md

@@ -10,7 +10,7 @@ The changelogs associated with the `docs-builder changelog` commands use the fol
 :::{important}
 Some of the fields in the schema accept only a specific set of values:
 
-- Product values must exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). Invalid products will cause the `docs-builder changelog add` command to fail.
+- Product values must exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). All products in the catalog are valid for changelogs, including those that have `public-reference` disabled. Invalid products will cause the `docs-builder changelog add` command to fail.
 - Type, subtype, and lifecycle values must match the available values defined in [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs), [ChangelogEntrySubtype.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntrySubtype.cs), and [Lifecycle.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs) respectively. Invalid values will cause the `docs-builder changelog add` command to fail.
 :::
 

docs/syntax/frontmatter.md

@@ -49,6 +49,7 @@ The products frontmatter is a list of products that the page relates to.
 This is used for the "Products" filter in the Search UI.
 
 The products frontmatter is a list of objects, each object has an `id` field.
+Only products with the `public-reference` feature enabled in [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) are valid here. Products that have set `public-reference: false` cannot be used in frontmatter.
 
 | Product ID                                  | Product Name                                  |
 |---------------------------------------------|-----------------------------------------------|

src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs

@@ -174,8 +174,8 @@ public ConfigurationFile(DocumentationSetFile docSetFile, IDocumentationSetConte
 				_substitutions[$"version.{alternativeName}.base"] = system.Base;
 			}
 
-			// Add product substitutions
-			foreach (var product in productsConfig.Products.Values)
+			// Add product substitutions (only for products with public-reference feature)
+			foreach (var product in productsConfig.PublicReferenceProducts.Values)
 			{
 				var alternativeProductId = product.Id.Replace('-', '_');
 				_substitutions[$"product.{product.Id}"] = product.DisplayName;

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

@@ -12,6 +12,13 @@ public record ProductsConfiguration
 {
 	public required FrozenDictionary<string, Product> Products { get; init; }
 
+	/// <summary>
+	/// Products with the <c>public-reference</c> feature enabled. These can appear in
+	/// applies_to blocks, page frontmatter, and get display-name substitutions.
+	/// When a product has no explicit <c>features</c> map, it is included here by default.
+	/// </summary>
+	public required FrozenDictionary<string, Product> PublicReferenceProducts { get; init; }
+
 	/// <summary>
 	/// Product id to display name mappings for fast lookups.
 	/// </summary>
@@ -54,12 +61,28 @@ public record ProductLink
 	public string Id { get; set; } = string.Empty;
 }
 
+/// <summary>Declares which docs-builder subsystems a product participates in.</summary>
+public record ProductFeatures
+{
+	/// <summary>Product can be referenced in applies_to blocks, page frontmatter, and gets display-name substitutions.</summary>
+	public bool PublicReference { get; init; }
+
+	/// <summary>Product participates in the changelog / release-notes system.</summary>
+	public bool ReleaseNotes { get; init; }
+
+	/// <summary>All features enabled -- the implicit default when no <c>features</c> map is present in YAML.</summary>
+	public static ProductFeatures All => new() { PublicReference = true, ReleaseNotes = true };
+
+	public static readonly FrozenSet<string> KnownKeys = FrozenSet.ToFrozenSet(["public-reference", "release-notes"], StringComparer.OrdinalIgnoreCase);
+}
+
 [YamlSerializable]
 public record Product
 {
 	public required string Id { get; init; }
 	public required string DisplayName { get; init; }
 	public VersioningSystem? VersioningSystem { get; init; }
 	public string? Repository { get; init; }
+	public ProductFeatures Features { get; init; } = ProductFeatures.All;
 }
 

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

@@ -18,24 +18,70 @@ public static ProductsConfiguration CreateProducts(this ConfigurationFileProvide
 
 		var products = productsDto.Products.ToDictionary(
 			kvp => kvp.Key,
-			kvp => new Product
+			kvp =>
 			{
-				Id = kvp.Key,
-				DisplayName = kvp.Value.Display,
-				VersioningSystem = versionsConfiguration.GetVersioningSystem(VersionsConfigurationExtensions.ToVersioningSystemId(kvp.Value.Versioning ?? kvp.Key)),
-				Repository = kvp.Value.Repository ?? kvp.Key
+				var features = ResolveFeatures(kvp.Key, kvp.Value.Features);
+				var versioningSystem = ResolveVersioningSystem(versionsConfiguration, kvp.Value.Versioning ?? kvp.Key);
+
+				versioningSystem ??= !features.PublicReference
+					? VersioningSystem.None
+					: throw new InvalidOperationException(
+						$"Product '{kvp.Key}' has invalid or missing versioning '{kvp.Value.Versioning ?? kvp.Key}' while 'public-reference' is enabled.");
+
+				return new Product
+				{
+					Id = kvp.Key,
+					DisplayName = kvp.Value.Display,
+					VersioningSystem = versioningSystem,
+					Repository = kvp.Value.Repository ?? kvp.Key,
+					Features = features
+				};
 			});
 
+		var publicReferenceProducts = products
+			.Where(kvp => kvp.Value.Features.PublicReference)
+			.ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
+
 		var productDisplayNames = productsDto.Products.ToDictionary(
 			kvp => kvp.Key,
 			kvp => kvp.Value.Display);
 
 		return new ProductsConfiguration
 		{
 			Products = products.ToFrozenDictionary(),
+			PublicReferenceProducts = publicReferenceProducts.ToFrozenDictionary(),
 			ProductDisplayNames = productDisplayNames.ToFrozenDictionary()
 		};
 	}
+
+	private static VersioningSystem? ResolveVersioningSystem(VersionsConfiguration versionsConfiguration, string id) =>
+		VersioningSystemIdExtensions.TryParse(id, out var versioningSystemId, ignoreCase: true, allowMatchingMetadataAttribute: true)
+			? versionsConfiguration.GetVersioningSystem(versioningSystemId)
+			: null;
+
+	private static ProductFeatures ResolveFeatures(string productId, Dictionary<string, bool>? featuresDto)
+	{
+		if (featuresDto is null)
+			return ProductFeatures.All;
+
+		var unknownKeys = featuresDto.Keys
+			.Where(k => !ProductFeatures.KnownKeys.Contains(k))
+			.ToList();
+
+		if (unknownKeys is { Count: > 0 })
+		{
+			var known = string.Join(", ", ProductFeatures.KnownKeys.Order());
+			throw new InvalidOperationException(
+				$"Product '{productId}' has unknown feature key(s): {string.Join(", ", unknownKeys)}. Known features: {known}."
+			);
+		}
+
+		return new ProductFeatures
+		{
+			PublicReference = featuresDto.GetValueOrDefault("public-reference", true),
+			ReleaseNotes = featuresDto.GetValueOrDefault("release-notes", true)
+		};
+	}
 }
 
 // Private DTOs for deserialization. These match the YAML structure directly.
@@ -52,5 +98,9 @@ internal sealed record ProductDto
 
 	[YamlMember(Alias = "versioning")]
 	public string? Versioning { get; set; }
+
 	public string? Repository { get; set; }
+
+	[YamlMember(Alias = "features")]
+	public Dictionary<string, bool>? Features { get; set; }
 }