From febc68d38fa9dcbd1747620c4a89cc313c276651 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 5 Dec 2025 13:08:56 -0800 Subject: [PATCH 1/2] 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/2] 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 +```