From febc68d38fa9dcbd1747620c4a89cc313c276651 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 5 Dec 2025 13:08:56 -0800 Subject: [PATCH 1/6] Add changelog docs --- docs/_docset.yml | 1 + docs/contribute/changelog.md | 62 ++++++++++++++++++++++++++++++++++++ docs/contribute/index.md | 1 + 3 files changed, 64 insertions(+) create mode 100644 docs/contribute/changelog.md diff --git a/docs/_docset.yml b/docs/_docset.yml index fd757a739..54fa412c9 100644 --- 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 diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md new file mode 100644 index 000000000..17f6eb19a --- /dev/null +++ b/docs/contribute/changelog.md @@ -0,0 +1,62 @@ +# Add changelog entries + +The `docs-builder changelog add` command creates a new changelog fragment file from command-line input. This is useful for creating changelog entries as part of your development workflow. + +## `docs-builder changelog add` + +Create a new changelog fragment with required and optional fields. For example: + +```sh +docs-builder changelog add \ + --title "Fixes enrich and lookup join resolution based on minimum transport version" \ + --type bug-fix \ + --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ + --areas "ES|QL" + --pr "https://github.com/elastic/elasticsearch/pull/137431" +``` + +:::{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. +- The command validates all values before generating the changelog file. If validation fails, no file is created. +- At this time, the PR value can be a number or a URL; it is not validated. +::: + +## 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"` + +## {{dbuild}} changelog add --help + +```sh +Usage: changelog add [options...] [-h|--help] [--version] + +Add a new changelog fragment from command-line input + +Options: + --title Required: A short, user-facing title (max 80 characters) (Required) + --type Required: Type of change (feature, enhancement, bug-fix, breaking-change, etc.) (Required) + --products > Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") (Required) + --subtype Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) (Default: null) + --areas Optional: Area(s) affected (comma-separated or specify multiple times) (Default: null) + --pr Optional: Pull request URL (Default: null) + --issues Optional: Issue URL(s) (comma-separated or specify multiple times) (Default: null) + --description Optional: Additional information about the change (max 600 characters) (Default: null) + --impact Optional: How the user's environment is affected (Default: null) + --action Optional: What users must do to mitigate (Default: null) + --feature-id Optional: Feature flag ID (Default: null) + --highlight Optional: Include in release highlights (Default: null) + --output Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null) + --config Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' (Default: null) +``` diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 0386949cd..21240317b 100644 --- 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 From be4574d69aa76ca6ae4bced7b3a5f9f43ccce0be Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 5 Dec 2025 14:50:44 -0800 Subject: [PATCH 2/6] More edits --- docs/contribute/_snippets/changelog-fields.md | 103 ++++++++++++++++ docs/contribute/changelog.md | 111 +++++++++++++----- 2 files changed, 182 insertions(+), 32 deletions(-) create mode 100644 docs/contribute/_snippets/changelog-fields.md diff --git a/docs/contribute/_snippets/changelog-fields.md b/docs/contribute/_snippets/changelog-fields.md new file mode 100644 index 000000000..2a36d8763 --- /dev/null +++ b/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 +``` diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md index 17f6eb19a..3cff558cd 100644 --- a/docs/contribute/changelog.md +++ b/docs/contribute/changelog.md @@ -1,43 +1,23 @@ # Add changelog entries -The `docs-builder changelog add` command creates a new changelog fragment file from command-line input. This is useful for creating changelog entries as part of your development workflow. +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. -## `docs-builder changelog add` - -Create a new changelog fragment with required and optional fields. For example: - -```sh -docs-builder changelog add \ - --title "Fixes enrich and lookup join resolution based on minimum transport version" \ - --type bug-fix \ - --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ - --areas "ES|QL" - --pr "https://github.com/elastic/elasticsearch/pull/137431" -``` - -:::{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. -- The command validates all values before generating the changelog file. If validation fails, no file is created. -- At this time, the PR value can be a number or a URL; it is not validated. +:::{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. ::: -## 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) +The command generates a YAML file that uses the following schema: -Examples: +:::{dropdown} Changelog schema +::::{include} /contribute/_snippets/changelog-fields.md +:::: +::: -- `"kibana 9.2.0 ga"` -- `"cloud-serverless 2025-08-05"` -- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` +## Command options -## {{dbuild}} changelog add --help +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] @@ -60,3 +40,70 @@ Options: --output Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null) --config 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 +``` From 03f65bf7e8515df40f1656b091a5a88200c5bc07 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 9 Dec 2025 14:11:39 -0800 Subject: [PATCH 3/6] Add docs to CLI section --- docs/_docset.yml | 4 ++++ docs/cli/index.md | 15 +++++++++++---- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/_docset.yml b/docs/_docset.yml index 54fa412c9..dd9d26547 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -153,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 index f9d9410a3..defe1d465 100644 --- 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,7 +33,7 @@ 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. @@ -40,8 +41,14 @@ Inbound links, those going from other sources to the documentation set, are vali [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) From 0d4c17fb06272ba8690d57d979857bc8946fdd0f Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 9 Dec 2025 14:37:39 -0800 Subject: [PATCH 4/6] Refine snippet --- docs/contribute/_snippets/changelog-fields.md | 28 +++---------------- 1 file changed, 4 insertions(+), 24 deletions(-) diff --git a/docs/contribute/_snippets/changelog-fields.md b/docs/contribute/_snippets/changelog-fields.md index 2a36d8763..d9a8d76a4 100644 --- a/docs/contribute/_snippets/changelog-fields.md +++ b/docs/contribute/_snippets/changelog-fields.md @@ -9,17 +9,7 @@ title: 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 +# Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values. products: @@ -29,6 +19,7 @@ products: # 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: @@ -40,10 +31,7 @@ products: lifecycle: # An optional string for new features and enhancements that have a specific availability. - # It can be one of the following: - # - preview - # - beta - # - ga + # 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: @@ -91,13 +79,5 @@ pr: 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 +# Refer to https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs for the acceptable values. ``` From 831717b3ebcb50a2672ebc20b7644c49436440f7 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 9 Dec 2025 14:52:00 -0800 Subject: [PATCH 5/6] Add ignored files --- docs/cli/release/changelog-add.md | 54 +++++++++++++++++++++++++++++++ docs/cli/release/index.md | 11 +++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/cli/release/changelog-add.md create mode 100644 docs/cli/release/index.md diff --git a/docs/cli/release/changelog-add.md b/docs/cli/release/changelog-add.md new file mode 100644 index 000000000..09f5acaa2 --- /dev/null +++ b/docs/cli/release/changelog-add.md @@ -0,0 +1,54 @@ +# 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 ` +: Optional: What users must do to mitigate. + +`--areas ` +: Optional: Areas affected (comma-separated or specify multiple times). + +`--config ` +: Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`. + +`--description ` +: Optional: Additional information about the change (max 600 characters). + +`--feature-id ` +: Optional: Feature flag ID + +`--highlight ` +: Optional: Include in release highlights. + +`--impact ` +: Optional: How the user's environment is affected. + +`--issues ` +: Optional: Issue numbers (comma-separated or specify multiple times). + +`--output ` +: Optional: Output directory for the changelog fragment. Defaults to current directory. + +`--products >` +: Required: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`). + +`--pr ` +: Optional: Pull request number. + +`--subtype ` +: Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`). + +`--title ` +: Required: A short, user-facing title (max 80 characters) + +`--type ` +: Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`) diff --git a/docs/cli/release/index.md b/docs/cli/release/index.md new file mode 100644 index 000000000..37c29bb46 --- /dev/null +++ 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 From 7580d01ddea17880c73c221b3a487297220c9013 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 9 Dec 2025 15:14:44 -0800 Subject: [PATCH 6/6] Add links --- docs/cli/release/changelog-add.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/cli/release/changelog-add.md b/docs/cli/release/changelog-add.md index 09f5acaa2..971e29bfd 100644 --- a/docs/cli/release/changelog-add.md +++ b/docs/cli/release/changelog-add.md @@ -40,15 +40,19 @@ docs-builder changelog add [options...] [-h|--help] `--products >` : 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 ` : Optional: Pull request number. `--subtype ` : 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 ` : Required: A short, user-facing title (max 80 characters) `--type ` -: Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`) +: 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).