Add changelog docs

docs/_docset.yml

@@ -1,3 +1,3 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
@@ -42,6 +42,7 @@
       - 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

docs/contribute/_snippets/changelog-fields.md

@@ -0,0 +1,103 @@
+
+```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.
+# It can be one of:
+# - feature: new functionality
+# - enhancement: extends functionality but does not break or fix existing behavior
+# - bug-fix: fixes a problem in a previous version
+# - known-issue: problems that we are aware of in a given version
+# - breaking-change: a change to previously-documented behavior
+# - deprecation: functionality that is being removed in a later release
+# - docs: major documentation updates or reorgs
+# - regression: functionality that no longer works or behaves incorrectly
+# - security: an advisory about potential security vulnerabilities
+# - other: does not fit into any of the other categories
+
+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.
+
+      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.
+      # It can be one of the following:
+      # - preview
+      # - beta
+      # - ga
+
+##### 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.
+# It can be one of:
+# - api: refers to changes that break an api
+# - behavioral: refers to changes the way something works
+# - configuration: refers to changes that break the configuration
+# - dependency: refers to changes like removing support for third-party products
+# - subscription: refers to changes that break licensing behavior
+# - plugin: refers to changes that break a plugin
+# - security: refers to changes that break authentication, authorization, or permissions
+# - other: does not fit into any of the other categories
+```

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
+```

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