Add product features support on products.yml

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 only have the 'release-notes' feature enabled).
 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:
+      release-notes: true
   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:
+      release-notes: true
 #...
 ```
 
@@ -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, only the listed features are active. 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 is only needed for products that should participate in a subset of features, such as internal tools that need release notes but don't have public-facing documentation.
+:::
 
 ## 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

@@ -12,13 +12,13 @@ The changelogs use the following schema:
 :::{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 only have the `release-notes` feature enabled. 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.
 :::
 
 To use the `docs-builder changelog` commands in your development workflow:
 
-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: { release-notes: true }`.
 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/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 (or no explicit `features` mapping) in [`products.yml`](https://github.com/elastic/docs-builder/blob/main/config/products.yml) are valid here. Products that only participate in release notes 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"),
+			ReleaseNotes = featuresDto.GetValueOrDefault("release-notes")
+		};
+	}
 }
 
 // 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; }
 }

src/Elastic.Documentation.Configuration/Versions/VersionConfiguration.cs

@@ -141,6 +141,9 @@ public enum VersioningSystemId
 	ElasticsearchClientRuby,
 	[Display(Name = "elasticsearch-client-rust")]
 	ElasticsearchClientRust,
+
+	[Display(Name = "none")]
+	None = -1,
 }
 
 [YamlSerializable]
@@ -152,6 +155,17 @@ public record VersioningSystem
 	/// </summary>
 	public const int VersionlessSentinel = 99999;
 
+	/// <summary>
+	/// A versionless sentinel for products that have no versioning system at all
+	/// (e.g. release-notes-only products without public documentation).
+	/// </summary>
+	public static VersioningSystem None { get; } = new()
+	{
+		Id = VersioningSystemId.None,
+		Base = new SemVersion(VersionlessSentinel, 0, 0),
+		Current = new SemVersion(VersionlessSentinel, 0, 0)
+	};
+
 	public required VersioningSystemId Id { get; init; }
 
 	[YamlMember(Alias = "base")]

src/Elastic.Markdown/Myst/FrontMatter/Products.cs

@@ -39,7 +39,7 @@ public object ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeseria
 		if (string.IsNullOrWhiteSpace(productId))
 			throw new InvalidProductException("Product 'id' field is required. Example format:\nproducts:\n  - id: apm", products);
 
-		if (products.Products.TryGetValue(productId.Replace('_', '-'), out var product))
+		if (products.PublicReferenceProducts.TryGetValue(productId.Replace('_', '-'), out var product))
 			return product;
 
 		throw new InvalidProductException(productId, products);
@@ -51,5 +51,5 @@ public object ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeseria
 public class InvalidProductException(string invalidValue, ProductsConfiguration products)
 	: Exception(
 		$"Invalid products frontmatter value: \"{invalidValue}\"." +
-		(!string.IsNullOrWhiteSpace(invalidValue) ? " " + new Suggestion(products.Products.Select(p => p.Value.Id).ToHashSet(), invalidValue).GetSuggestionQuestion() : "") +
+		(!string.IsNullOrWhiteSpace(invalidValue) ? " " + new Suggestion(products.PublicReferenceProducts.Select(p => p.Value.Id).ToHashSet(), invalidValue).GetSuggestionQuestion() : "") +
 		"\nYou can find the full list at https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/frontmatter#products.");

src/Elastic.Markdown/Myst/YamlSerialization.cs

@@ -23,7 +23,7 @@ public static T Deserialize<T>(string yaml, ProductsConfiguration products)
 			.WithEnumNamingConvention(HyphenatedNamingConvention.Instance)
 			.WithTypeConverter(new SemVersionConverter())
 			.WithTypeConverter(new ProductConverter(products))
-			.WithTypeConverter(new ApplicableToYamlConverter(products.Products.Keys))
+			.WithTypeConverter(new ApplicableToYamlConverter(products.PublicReferenceProducts.Keys))
 			.Build();
 
 		var frontMatter = deserializer.Deserialize<T>(input);

tests-integration/Elastic.Assembler.IntegrationTests/TestHelpers.cs

@@ -54,6 +54,7 @@ public static IConfigurationContext CreateConfigurationContext(
 			productsConfiguration = new ProductsConfiguration
 			{
 				Products = products.ToFrozenDictionary(),
+				PublicReferenceProducts = products.ToFrozenDictionary(),
 				ProductDisplayNames = products.ToDictionary(p => p.Key, p => p.Value.DisplayName).ToFrozenDictionary()
 			};
 		}

tests-integration/Mcp.Remote.IntegrationTests/McpToolsIntegrationTestsBase.cs

@@ -121,6 +121,7 @@ private static ProductsConfiguration CreateProductsConfiguration()
 		return new ProductsConfiguration
 		{
 			Products = products.ToFrozenDictionary(),
+			PublicReferenceProducts = products.ToFrozenDictionary(),
 			ProductDisplayNames = productDisplayNames.ToFrozenDictionary()
 		};
 	}

tests/Elastic.ApiExplorer.Tests/TestHelpers.cs

@@ -50,6 +50,7 @@ public static IConfigurationContext CreateConfigurationContext(IFileSystem fileS
 			productsConfiguration = new ProductsConfiguration
 			{
 				Products = products.ToFrozenDictionary(),
+				PublicReferenceProducts = products.ToFrozenDictionary(),
 				ProductDisplayNames = products.ToDictionary(p => p.Key, p => p.Value.DisplayName).ToFrozenDictionary()
 			};
 		}

tests/Elastic.Changelog.Tests/Changelogs/ChangelogTestBase.cs

@@ -93,6 +93,7 @@ protected ChangelogTestBase(ITestOutputHelper output)
 		var productsConfiguration = new ProductsConfiguration
 		{
 			Products = products.ToFrozenDictionary(),
+			PublicReferenceProducts = products.ToFrozenDictionary(),
 			ProductDisplayNames = products.ToDictionary(p => p.Key, p => p.Value.DisplayName).ToFrozenDictionary()
 		};
 

tests/Elastic.Documentation.Build.Tests/TestHelpers.cs

@@ -58,6 +58,7 @@ public static IConfigurationContext CreateConfigurationContext(
 			productsConfiguration = new ProductsConfiguration
 			{
 				Products = products.ToFrozenDictionary(),
+				PublicReferenceProducts = products.ToFrozenDictionary(),
 				ProductDisplayNames = products.ToDictionary(p => p.Key, p => p.Value.DisplayName).ToFrozenDictionary()
 			};
 		}

tests/Elastic.Documentation.Configuration.Tests/CrossLinkRegistryTests.cs

@@ -118,6 +118,7 @@ private static ConfigurationFile CreateConfiguration(DocumentationSetFile docSet
 		var productsConfig = new ProductsConfiguration
 		{
 			Products = new Dictionary<string, Product>().ToFrozenDictionary(),
+			PublicReferenceProducts = new Dictionary<string, Product>().ToFrozenDictionary(),
 			ProductDisplayNames = new Dictionary<string, string>().ToFrozenDictionary()
 		};
 

tests/Elastic.Documentation.Configuration.Tests/DocumentInferrerServiceTests.cs

@@ -81,6 +81,7 @@ private static ProductsConfiguration CreateProductsConfiguration(VersionsConfigu
 		return new ProductsConfiguration
 		{
 			Products = products.ToFrozenDictionary(),
+			PublicReferenceProducts = products.ToFrozenDictionary(),
 			ProductDisplayNames = products.ToDictionary(p => p.Key, p => p.Value.DisplayName).ToFrozenDictionary()
 		};
 	}
@@ -396,6 +397,7 @@ public void InferForMarkdownWithVersionlessProductReturnsNullVersion()
 		var productsConfig = new ProductsConfiguration
 		{
 			Products = products.ToFrozenDictionary(),
+			PublicReferenceProducts = products.ToFrozenDictionary(),
 			ProductDisplayNames = products.ToDictionary(p => p.Key, p => p.Value.DisplayName).ToFrozenDictionary()
 		};
 		var legacyUrlMappings = new LegacyUrlMappingConfiguration { Mappings = [] };