Merge branch 'main' into fix/versioning_dropdown

cotti · web-flow · commit cc2e6ffe7a6d · 2025-12-10T15:55:56.000-03:00
diff --git a/docs/_docset.yml b/docs/_docset.yml
@@ -42,6 +42,7 @@ toc:
       - file: branching-strategy.md
       - file: add-repo.md
       - file: release-new-version.md
+      - file: changelog.md
       - hidden: locally.md
       - hidden: on-the-web.md
   - folder: building-blocks
@@ -152,6 +153,10 @@ toc:
           - file: inbound-links-validate.md
           - file: inbound-links-validate-all.md
           - file: inbound-links-validate-link-reference.md
+      - folder: release
+        children:
+          - file: index.md
+          - file: changelog-add.md
   - folder: migration
     children:
       - file: index.md
diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -5,11 +5,12 @@ navigation_title: CLI (docs-builder)
 # Command line interface
 
 `docs-builder` is the binary used to invoke various commands. 
-These commands can be roughly grouped into three main categories
+These commands can be roughly grouped into four main categories
 
 - [Documentation Set commands](#documentation-set-commands)
 - [Link commands](#link-commands)
 - [Assembler commands](#assembler-commands)
+- [Release doc commands](#release-doc-commands)
 
 ### Global options 
 
@@ -22,7 +23,7 @@ The following options are available for all commands:
 :   Explicitly set the configuration source one of `local`, `remote` or `embedded`. Defaults to `local` if available 
     other wise `embedded`
 
-## Documentation Set Commands
+## Documentation set commands
 
 Commands that operate over a single documentation set.
 
@@ -32,16 +33,22 @@ These commands are typically what you interface with when you are working on the
 
 [See available CLI commands for documentation sets](docset/index.md) 
 
-## Link Commands
+## Link commands
 
 Outbound links, those going from the documentation set to other sources, are validated as part of the build process.
 
 Inbound links, those going from other sources to the documentation set, are validated using specialized commands.
 
 [See available CLI commands for inbound links](links/index.md) 
 
-## Assembler Commands
+## Assembler commands
 
 Assembler builds bring together all isolated documentation set builds and turn them into the overall documentation that gets published.
 
 [See available CLI commands for assembler](assembler/index.md)
+
+## Release doc commands
+
+Commands that pertain to creating and publishing product release documentation.
+
+[See available CLI commands for release docs](release/index.md)
diff --git a/docs/cli/release/changelog-add.md b/docs/cli/release/changelog-add.md
@@ -0,0 +1,58 @@
+# changelog add
+
+Create a changelog file that describes a single item in the release documentation.
+For details and examples, go to [](/contribute/changelog.md).
+
+## Usage
+
+```sh
+docs-builder changelog add [options...] [-h|--help]
+```
+
+## Options
+
+`--action <string?>`
+:   Optional: What users must do to mitigate.
+
+`--areas <string[]?>`
+:   Optional: Areas affected (comma-separated or specify multiple times).
+
+`--config <string?>`
+:   Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`.
+
+`--description <string?>`
+:   Optional: Additional information about the change (max 600 characters).
+
+`--feature-id <string?>`
+:   Optional: Feature flag ID
+
+`--highlight <bool?>`
+:   Optional: Include in release highlights.
+
+`--impact <string?>`
+:   Optional: How the user's environment is affected.
+
+`--issues <string[]?>`
+:   Optional: Issue numbers (comma-separated or specify multiple times).
+
+`--output <string?>`
+:   Optional: Output directory for the changelog fragment. Defaults to current directory.
+
+`--products <List<ProductInfo>>`
+:   Required: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`).
+:   The valid product identifiers are listed in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
+:   The valid lifecycles are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
+
+`--pr <string?>`
+:   Optional: Pull request number.
+
+`--subtype <string?>`
+:   Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`).
+:   The valid subtypes are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
+
+`--title <string>`
+:    Required: A short, user-facing title (max 80 characters)
+
+`--type <string>`
+:   Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).
+:   The valid types are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
diff --git a/docs/cli/release/index.md b/docs/cli/release/index.md
@@ -0,0 +1,11 @@
+---
+navigation_title: "release"
+---
+
+# Release doc commands
+
+These commands are associated with product release documentation.
+
+## Changelog commands
+
+- [changelog add](changelog-add.md) - Create a changelog file
diff --git a/docs/contribute/_snippets/changelog-fields.md b/docs/contribute/_snippets/changelog-fields.md
@@ -0,0 +1,83 @@
+
+```yaml
+##### Required fields #####
+title:
+
+# A required string that is a short, user-facing headline
+# Max 80 characters
+
+type: 
+
+# A required string that contains the type of change.
+# Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values.
+
+products:
+
+# A required array of objects that denote the affected products and their target release.
+
+    - product:
+
+      # A required string with a predefined product ID used for release note routing,
+      # filters, and categorization.
+      # Refer to https://github.com/elastic/docs-builder/blob/main/config/products.yml for the acceptable values.
+      
+      target:
+
+      # An optional string that facilitates pre-release doc previews.
+      # For products with version releases, it contains the target version number (V.R.M).
+      # For products with date releases, it contains the target release date
+      # or the date the PR was merged.
+
+      lifecycle:
+
+      # An optional string for new features and enhancements that have a specific availability.
+      # Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values.
+
+##### Optional fields #####
+action:
+
+# An optional string that describes what users must do to mitigate the impact
+# of a breaking change or known issue.
+
+areas:
+
+# An optional array of strings that denotes the parts/components/services of the
+# product that are specifically affected.
+# The list of valid values will vary by product.
+# The docs for each release typically group the changes by type then by area.
+
+description:
+
+# An optional string that provides additional information about what has changed.
+# Max 600 characters
+
+feature-id:
+
+# An optional string to associate a feature or enhancement with a unique feature flag
+
+highlight:
+
+# An optional boolean for items that should be included in release highlights
+# or the UI to draw users' attention.
+
+impact:
+
+# An optional string that describes how the user's environment is/will be
+# affected by a breaking change.
+
+issues:
+
+# An optional array of strings that contain URLs for issues that are relevant to the PR.
+# They are externalized in the release docs so users can follow the links and
+# understand the context.
+
+pr: 
+
+# An optional string that contains the pull request identifier.
+# It is externalized in the release docs so users can follow the link and find more details.
+
+subtype:
+
+# An optional string that applies only to breaking changes and further subdivides that type.
+# Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values.
+```
diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md
@@ -0,0 +1,109 @@
+# Add changelog entries
+
+The `docs-builder changelog add` command creates a new changelog file from command-line input.
+By adding a file for each notable change, you can ultimately generate release documention with a consistent layout for all your products.
+
+:::{note}
+This command is associated with an ongoing release docs initiative.
+Additional workflows are still to come for managing the list of changelogs in each release.
+:::
+
+The command generates a YAML file that uses the following schema:
+
+:::{dropdown} Changelog schema
+::::{include} /contribute/_snippets/changelog-fields.md
+::::
+:::
+
+## Command options
+
+The command supports all of the following options, which generally align with fields in the changelog schema:
+
+```sh
+Usage: changelog add [options...] [-h|--help] [--version]
+
+Add a new changelog fragment from command-line input
+
+Options:
+  --title <string>                  Required: A short, user-facing title (max 80 characters) (Required)
+  --type <string>                   Required: Type of change (feature, enhancement, bug-fix, breaking-change, etc.) (Required)
+  --products <List<ProductInfo>>    Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") (Required)
+  --subtype <string?>               Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) (Default: null)
+  --areas <string[]?>               Optional: Area(s) affected (comma-separated or specify multiple times) (Default: null)
+  --pr <string?>                    Optional: Pull request URL (Default: null)
+  --issues <string[]?>              Optional: Issue URL(s) (comma-separated or specify multiple times) (Default: null)
+  --description <string?>           Optional: Additional information about the change (max 600 characters) (Default: null)
+  --impact <string?>                Optional: How the user's environment is affected (Default: null)
+  --action <string?>                Optional: What users must do to mitigate (Default: null)
+  --feature-id <string?>            Optional: Feature flag ID (Default: null)
+  --highlight <bool?>               Optional: Include in release highlights (Default: null)
+  --output <string?>                Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null)
+  --config <string?>                Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' (Default: null)
+```
+
+### Product format
+
+The `--products` parameter accepts products in the format `"product target lifecycle, ..."` where:
+
+- `product` is the product ID from [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required)
+- `target` is the target version or date (optional)
+- `lifecycle` is one of: `preview`, `beta`, or `ga` (optional)
+
+Examples:
+
+- `"kibana 9.2.0 ga"`
+- `"cloud-serverless 2025-08-05"`
+- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"`
+
+## Changelog configuration
+
+Some of the fields in the changelog accept only a specific set of values.
+
+:::{important}
+
+- Product values must exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). Invalid products will cause the command to fail.
+- Type, subtype, and lifecycle values must match the available values defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). Invalid values will cause the command to fail.
+:::
+
+If you want to further limit the list of values, you can optionally create a configuration file.
+Refer to [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example).
+
+By default, the command checks the following path: `docs/changelog.yml`.
+You can specify a different path with the `--config` command option.
+
+If a configuration file exists, the command validates all its values before generating the changelog file:
+
+- If the configuration file contains `lifecycle`, `product`, `subtype`, or `type` values that don't match the values in `products.yml` and `ChangelogConfiguration.cs`, validation fails. The changelog file is not created.
+- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails. The changelog file is not created.
+
+## Examples
+
+The following command creates a changelog for a bug fix that applies to two products:
+
+```sh
+docs-builder changelog add \
+  --title "Fixes enrich and lookup join resolution based on minimum transport version" \
+  --type bug-fix \ <1>
+  --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ <2>
+  --areas "ES|QL"
+  --pr "https://github.com/elastic/elasticsearch/pull/137431" <3>
+```
+
+1. The type values are defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
+2. The product values are defined in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
+3. At this time, the PR value can be a number or a URL; it is not validated.
+
+The output file has the following format:
+
+```yaml
+pr: https://github.com/elastic/elasticsearch/pull/137431
+type: bug-fix
+products:
+- product: elasticsearch
+  target: 9.2.3
+- product: cloud-serverless
+  target: 2025-12-02
+title: Fixes enrich and lookup join resolution based on minimum transport version
+areas:
+- ES|QL
+```
diff --git a/docs/contribute/index.md b/docs/contribute/index.md
@@ -10,6 +10,7 @@ Use these guides for tasks like managing documentation files and folders, config
 
 - [Move files and folders](move.md): Move files or folders and automatically update all links in the documentation.
 - [Manage redirects across doc sets](redirects.md): Set up redirects when moving or deleting pages to prevent broken links.
+- [Add changelog entries](changelog.md): Create changelog fragments using the command-line interface.
 
 ## Repository management
 
diff --git a/src/services/Elastic.Documentation.Services/ChangelogService.cs b/src/services/Elastic.Documentation.Services/ChangelogService.cs
