From 4fe1b1b2a6324dd52e53b2a8a790a3dc6f88a1b2 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 22 Apr 2026 19:27:12 -0700 Subject: [PATCH 1/6] [DOCS] Edit changelog creation how-to --- docs/cli/changelog/add.md | 42 +++++- docs/contribute/configure-changelogs.md | 42 +++++- docs/contribute/create-changelogs.md | 189 ++++++++++-------------- 3 files changed, 156 insertions(+), 117 deletions(-) diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index 23fe870fe9..c30be4cbd0 100644 --- a/docs/cli/changelog/add.md +++ b/docs/cli/changelog/add.md @@ -123,10 +123,16 @@ docs-builder changelog add [options...] [-h|--help] : The valid types are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs). `--use-pr-number` -: Optional: Use PR numbers for filenames instead of the configured `filename` strategy. With both `--prs` (which creates one changelog per specified PR) and `--issues` (which creates one changelog per specified issue), each changelog filename will be derived from its PR numbers. Requires `--prs` or `--issues`. Mutually exclusive with `--use-issue-number`. +: Optional: Use PR numbers for filenames instead of the configured `filename` strategy. +: Requires `--prs` or `--issues`. +: Mutually exclusive with `--use-issue-number`. +: Refer to [](#filenames). `--use-issue-number` -: Optional: Use issue numbers for filenames instead of the configured `filename` strategy. With both `--prs` (which creates one changelog per specified PR) and `--issues` (which creates one changelog per specified issue), each changelog filename will be derived from its issues. Requires `--prs` or `--issues`. Mutually exclusive with `--use-pr-number`. +: Optional: Use issue numbers for filenames instead of the configured `filename` strategy. +: Requires `--prs` or `--issues`. +: Mutually exclusive with `--use-pr-number`. +: Refer to [](#filenames). ## CI auto-detection [ci-auto-detection] @@ -158,6 +164,38 @@ This allows the CI action to invoke `changelog add` with a minimal command line: docs-builder changelog add --config docs/changelog.yml --output /tmp/staging --concise --strip-title-prefix ``` +## Filenames + +By default, output files are named according to the `filename` strategy in `changelog.yml`: + +| Strategy | Example filename | Description | +|---|---|---| +| `timestamp` (default) | `1735689600-fixes-enrich-and-lookup-join-resolution.yaml` | Uses a Unix timestamp with a sanitized title slug. | +| `pr` | `137431.yaml` | Uses the PR number. | +| `issue` | `2571.yaml` | Uses the issue number. | + +Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) or [](/contribute/configure-changelogs-ref.md). + +You can override those settings with the `--use-pr-number` or `--use-issue-number` CLI flags: + +```sh +docs-builder changelog add \ + --prs 1234 \ + --products "elasticsearch 9.2.3" \ + --use-pr-number + +docs-builder changelog add \ + --issues 4567 \ + --products "elasticsearch 9.3.0" \ + --use-issue-number +``` + +:::{important} +`--use-pr-number` and `--use-issue-number` are mutually exclusive; specify only one. Each requires `--prs` or `--issues`. The numbers are extracted from the URLs or identifiers you provide or from linked references in the issue or PR body when extraction is enabled. + +**Precedence**: CLI flags (`--use-pr-number` / `--use-issue-number`) > `filename` in `changelog.yml` > default (`timestamp`). +::: + ## Products resolution [products-resolution] When you run the `changelog add` command without the `--products` option, it resolves products in the following order: diff --git a/docs/contribute/configure-changelogs.md b/docs/contribute/configure-changelogs.md index e749095c5b..7dfc230b27 100644 --- a/docs/contribute/configure-changelogs.md +++ b/docs/contribute/configure-changelogs.md @@ -1,13 +1,45 @@ # Configure changelogs -Before you can use the `docs-builder changelog` commands in your development workflow, you must make some decisions and do some setup steps: +Before you can use the `docs-builder changelog` commands, you must evaluate your GitHub label strategy and verify that the necessary product metadata exists. +You can then set up a changelog configuration file to make the content workflow more automated and repeatable. + +## Before you begin 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: { public-reference: false }`. For more information, refer to [Products](/configure/site/products.md). -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`). -After you collect all this information, you can use it to make the changelog process more automated and repeatable by setting up a changelog configuration file. +1. Optional: Choose the GitHub labels that you'll use to automatically derive some changelog fields. + + 1. Create labels for _types_. The supported types are defined in [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs). At a minimum, add labels for the `feature`, `bug-fix`, and `breaking-change` types. + + 1. Create labels for _products_. If your repo only pertains to a single product or you don't want to use labels to accomplish this classification, this step is not required. + + 1. Create labels for _areas_ (or "features" or "components") of your products. If you don't want to show categories (other than the default "type" categories) in your documentation, this step is not required. + + 1. Create labels to opt in or out of changelogs. For example, create `non-issue` or `release_notes:skip` labels for PRs that _shouldn't_ have changelogs. Alternatively, create a `@Public` label to identify PRs that _should_ have changelogs. You can only choose one label strategy for this behavior: exclusion or inclusion. + + 1. Create labels for _highlights_. This step is not required unless you want to publish release highlights. + +1. If you'll be accessing GitHub from the command line, set up the necessary privileges as described in the following section. + +### Authorization + +Any of the `docs-builder changelog` commands that access GitHub require authority to view your pull requests and issues. +For example, this authority is required if you'll be running any of these [changelog commands](/cli/changelog/index.md) from the command line: `changelog add`, `changelog bundle`, `changelog gh-release`. + +You must log into GitHub or set the `GITHUB_TOKEN` (or `GH_TOKEN` ) environment variable with a sufficient personal access token (PAT) to pull information from your repository. +Otherwise, there will be fetch failures when you access private repositories and you might also encounter GitHub rate limiting errors. + +For example, to create a new token with the minimum authority to read pull request details: + + 1. Go to **GitHub Settings** > **Developer settings** > **Personal access tokens** > [Fine-grained tokens](https://github.com/settings/personal-access-tokens). + 1. Click **Generate new token**. + 1. Give your token a descriptive name (such as "docs-builder changelog"). + 1. Under **Resource owner** if you're an Elastic employee, select **Elastic**. + 1. Set an expiration date. + 1. Under **Repository access**, select **Only select repositories** and choose the repositories you want to access. + 1. Under **Permissions** > **Repository permissions**, set **Pull requests** to **Read-only**. If you want to be able to read issue details, do the same for **Issues**. + 1. Click **Generate token**. + 1. Copy the token to a safe location and use it in the `GITHUB_TOKEN` environment variable. ## Create a changelog configuration file [changelog-settings] diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index 3f1b85031e..b25b9ba482 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -1,140 +1,96 @@ # Create changelogs -The changelogs associated with the `docs-builder changelog` commands use the following schema: +You can use `docs-builder changelog` commands to create data files ("changelogs") for each notable change in your GitHub repository. +These files are ultimately used to generate release documentation. -:::{dropdown} Changelog schema -::::{include} /contribute/_snippets/changelog-fields.md -:::: -::: +This page describes how to create these files both from the [command line](#command-line) and from [GitHub actions](#github-actions). -:::{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). All products in the catalog are valid for changelogs, including those that have `public-reference` disabled. 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. -::: +## Before you begin -## Create changelog files [changelog-add] +Create a changelog configuration file to define all the default behavior and PR label mappings. +Refer to [](/contribute/configure-changelogs.md). -You can use the `docs-builder changelog add` command to create a changelog file. +## Create changelog files from command line [command-line] -If you specify `--prs` or `--issues`, the command tries to fetch information from GitHub. It derives the changelog `title` from the pull request or issue title, maps labels to areas, products, and type (if configured), and extracts linked references. -With `--issues`, it extracts linked PRs from the issue body (for example, "Fixed by #123"). -With `--prs`, it extracts linked issues from the PR body (for example, "Fixes #123"). +These steps describe how to use the [changelog add](/cli/changelog/add.md) command. +If you already have automated release notes for GitHub releases, you can use the [changelog gh-release](/cli/changelog/gh-release.md) command instead. -When `--repo`, `--owner`, or `--output` are not specified, the command reads them from the `bundle` section of `changelog.yml` (`bundle.repo`, `bundle.owner`, `bundle.directory`). This applies to all modes — `--prs`, `--issues`, and `--release-version` alike. If no config value is available, `--owner` defaults to `elastic` and `--output` defaults to the current directory. +1. If you're accessing private repositories or creating a large number of changelogs, log into GitHub or set the `GITHUB_TOKEN` (or `GH_TOKEN` ) environment variable with a sufficient personal access token. Refer to [Authorization](/contribute/configure-changelogs.md#authorization). -:::{tip} -Ideally this task will be automated such that it's performed by a bot or GitHub action when you create a pull request. -If you run it from the command line, you must precede any special characters (such as backquotes) with a backslash escape character (`\`). -::: - -### CI two-step flow - -When automated via the [changelog GitHub Actions](https://github.com/elastic/docs-actions/tree/main/changelog), changelog creation is a two-step process: - -1. **`changelog evaluate-pr`** inspects the PR (title, labels, body) and produces outputs such as `title`, `type`, `description`, and `products`. -2. **`changelog add`** reads those outputs from `CHANGELOG_*` environment variables and generates the changelog YAML file. - -The `description` output from step 1 contains the release note extracted from the PR body (when `extract.release_notes` is enabled). If extraction is disabled — either by setting `extract.release_notes: false` in `changelog.yml` or by passing `--no-extract-release-notes` to `changelog add` — the `CHANGELOG_DESCRIPTION` environment variable is ignored and the extracted description is not written to the changelog. - -Refer to [CI auto-detection](/cli/changelog/add.md#ci-auto-detection) for the full list of environment variables and precedence rules. +1. Run the `changelog add` command in your GitHub repo's root directory. + For example: -For up-to-date command usage information, use the `-h` option or refer to [](/cli/changelog/add.md). + ```sh + docs-builder changelog add \ + --title "Improve SAML error handling by adding metadata" + --type enhancement + --products "elasticsearch 9.2.8, cloud-serverless 2026-02-02" + ``` -### Authorization + Title, type, and products are the minimal details required for each changelog file. -If you use the `--prs`, `--issues`, or `--release-version` options, the `docs-builder changelog add` command interacts with GitHub services. -The `--release-version` option on the `docs-builder changelog add`, `bundle`, and `remove` commands also interacts with GitHub services. -Log into GitHub or set the `GITHUB_TOKEN` (or `GH_TOKEN` ) environment variable with a sufficient personal access token (PAT). -Otherwise, there will be fetch failures when you access private repositories and you might also encounter GitHub rate limiting errors. + :::{tip} + Any special characters (such as backquotes) must be preceded with a backslash escape character (`\`). + ::: -For example, to create a new token with the minimum authority to read pull request details: + Alternatively, pull the information from GitHub: -1. Go to **GitHub Settings** > **Developer settings** > **Personal access tokens** > [Fine-grained tokens](https://github.com/settings/personal-access-tokens). -2. Click **Generate new token**. -3. Give your token a descriptive name (such as "docs-builder changelog"). -4. Under **Resource owner** if you're an Elastic employee, select **Elastic**. -5. Set an expiration date. -6. Under **Repository access**, select **Only select repositories** and choose the repositories you want to access. -7. Under **Permissions** > **Repository permissions**, set **Pull requests** to **Read-only**. If you want to be able to read issue details, do the same for **Issues**. -8. Click **Generate token**. -9. Copy the token to a safe location and use it in the `GITHUB_TOKEN` environment variable. + ```sh + docs-builder changelog add \ + --prs https://github.com/elastic/elasticsearch/pull/137598 + ``` -### Product format + The `--prs` value can be a full URL (such as `https://github.com/owner/repo/pull/123`), a short format (such as `owner/repo#123`), just a number, or a path to a file containing newline-delimited PR URLs. Multiple PRs can be provided comma-separated. One changelog is created for each PR. -The `docs-builder changelog add` has a `--products` option and the `docs-builder changelog bundle` has `--input-products` and `--output-products` options that all use the same format. + When you specify `--prs` or `--issues`, the command tries to fetch information from GitHub. + It derives the title from the pull request or issue title, extracts linked references, and derives the areas, products, and type from labels (if mappings are defined in the configuration file). -They accept values with the format `"product target lifecycle, ..."` where: + For the most up-to-date command syntax, use the `-h` option or refer to [](/cli/changelog/add.md). -- `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) +1. [Review the output file](#review). -Examples: +## Create changelogs from GitHub actions [github-actions] -- `"kibana 9.2.0 ga"` -- `"cloud-serverless 2025-08-05"` -- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` +When automated via the [changelog GitHub Actions](https://github.com/elastic/docs-actions/tree/main/changelog), changelog creation is a two-step process: -### Filenames +1. `changelog evaluate-pr` inspects the PR (title, labels, body) and produces outputs such as `title`, `type`, `description`, and `products`. +2. `changelog add` reads those outputs from `CHANGELOG_*` environment variables and generates the changelog YAML file. -The `docs-builder changelog add` command names generated files according to the `filename` strategy in `changelog.yml`: +The `description` output from step 1 contains the release note extracted from the PR body (when `extract.release_notes` is enabled). +If extraction is disabled (either by setting `extract.release_notes: false` in `changelog.yml` or by passing `--no-extract-release-notes` to `changelog add`), the `CHANGELOG_DESCRIPTION` environment variable is ignored and the extracted description is not written to the changelog. -| Strategy | Example filename | Description | -|---|---|---| -| `timestamp` (default) | `1735689600-fixes-enrich-and-lookup-join-resolution.yaml` | Uses a Unix timestamp with a sanitized title slug. | -| `pr` | `137431.yaml` | Uses the PR number. | -| `issue` | `2571.yaml` | Uses the issue number. | +Refer to [CI auto-detection](/cli/changelog/add.md#ci-auto-detection) for the full list of environment variables and precedence rules. -Set the strategy in your changelog configuration file: +## Review the content [review] -```yaml -filename: timestamp -``` +1. Find the files that were created by the command or GitHub action. -Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) for full documentation. + You can specify the file location with command options (`--output`) or configuration options (`bundle.directory`). + Likewise you can control the file names with command options (`--use-issue-number` or `--use-pr-number`) or the `filename` configuration option. + Refer to the [Filenames](/cli/changelog/add.md#filenames). -You can override the configured strategy per invocation with the `--use-pr-number` or `--use-issue-number` CLI flags: +1. Verify that the files contain content that is accurate and user-friendly. + This review is especially important when you're pulling content from GitHub, since there might be some missing or extraneous information. -```sh -docs-builder changelog add \ - --prs https://github.com/elastic/elasticsearch/pull/137431 \ - --products "elasticsearch 9.2.3" \ - --use-pr-number +Changelog files use the following schema: -docs-builder changelog add \ - --issues https://github.com/elastic/docs-builder/issues/2571 \ - --products "elasticsearch 9.3.0" \ - --config docs/changelog.yml \ - --use-issue-number -``` - -:::{important} -`--use-pr-number` and `--use-issue-number` are mutually exclusive; specify only one. Each requires `--prs` or `--issues`. The numbers are extracted from the URLs or identifiers you provide, or from linked references in the issue or PR body when extraction is enabled. - -**Precedence**: CLI flags (`--use-pr-number` / `--use-issue-number`) > `filename` in `changelog.yml` > default (`timestamp`). +:::{dropdown} Changelog schema +::::{include} /contribute/_snippets/changelog-fields.md +:::: ::: -### Examples +For content guidelines, go to [Changelogs](https://www.elastic.co/docs/contribute-docs/content-types/changelogs). -#### Create a changelog for multiple products [example-multiple-products] +:::{note} +Some of the fields in the schema accept only a specific set of values: -```sh -docs-builder changelog add \ - --title "Fixes enrich and lookup join resolution based on minimum transport version" \ <1> - --type bug-fix \ <2> - --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ <3> - --areas "ES|QL" - --prs "https://github.com/elastic/elasticsearch/pull/137431" <4> -``` +- Product values must exist in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). +- 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. +::: -1. This option is required only if you want to override what's derived from the PR title. -2. The type values are defined in [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs). -3. The product values are defined in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml). -4. The `--prs` value can be a full URL (such as `https://github.com/owner/repo/pull/123`), a short format (such as `owner/repo#123`), just a number (in which case you must also provide `--owner` and `--repo` options), or a path to a file containing newline-delimited PR URLs or numbers. Multiple PRs can be provided comma-separated, or you can specify a file path. You can also mix both formats by specifying `--prs` multiple times. One changelog file will be created for each PR. +## Examples -#### Create a changelog with PR label mappings [example-map-label] +### Create a changelog with PR label mappings [example-map-label] You can configure label mappings in your changelog configuration file: @@ -183,7 +139,8 @@ docs-builder changelog add \ --strip-title-prefix ``` -In this case, the changelog file derives the title, type, areas, and products from the pull request. If none of the PR's labels match `pivot.products`, the command falls back to `products.default` or repository name inference from `--repo` (refer to [Products resolution](/cli/changelog/add.md#products-resolution) for more details). +In this case, the changelog file derives the title, type, areas, and products from the pull request. +If none of the PR's labels match `pivot.products`, the command falls back to `products.default` or repository name inference from `--repo` (refer to [Products resolution](/cli/changelog/add.md#products-resolution) for more details). The command also looks for patterns like `Fixes #123`, `Closes owner/repo#456`, `Resolves https://github.com/.../issues/789` in the pull request to derive its issues. Similarly, when using `--issues`, the command extracts linked PRs from the issue body (for example, "Fixed by #123"). You can turn off this behavior in either case with the `--no-extract-issues` flag or by setting `extract.issues: false` in the changelog configuration file. The `extract.issues` setting applies to both directions: issues extracted from PR bodies (when using `--prs`) and PRs extracted from issue bodies (when using `--issues`). The `--strip-title-prefix` option in this example means that if the PR title has a prefix in square brackets (such as `[ES|QL]` or `[Security]`), it is automatically removed from the changelog title. Multiple square bracket prefixes are also supported (for example `[Discover][ESQL] Title` becomes `Title`). If a colon follows the closing bracket, it is also removed. @@ -194,7 +151,7 @@ By default, `--strip-title-prefix` is disabled. You can enable it globally by se The `--strip-title-prefix` option only applies when the title is derived from the PR (when `--title` is not explicitly provided). If you specify `--title` explicitly, that title is used as-is without any prefix stripping. ::: -#### Extract release notes from PR descriptions [example-extract-release-notes] +### Extract release notes from PR descriptions [example-extract-release-notes] When you use the `--prs` option, by default the `docs-builder changelog add` command automatically extracts text from the PR descriptions and use it in your changelog. @@ -217,7 +174,7 @@ If you explicitly provide `--title` or `--description`, those values take preced You can turn off the release note extraction in the changelog configuration file or by using the `--no-extract-release-notes` option. ::: -#### Control changelog creation [example-block-label] +### Control changelog creation [example-block-label] You can prevent changelog creation for certain PRs based on their labels. @@ -264,7 +221,7 @@ rules: include: "@Public, @Notable" ``` -#### Create changelogs from a file [example-file-add] +### Create changelogs from a file [example-file-add] You can create multiple changelogs in a single command by providing a newline-delimited file that contains pull requests or issues. For example: @@ -284,7 +241,7 @@ docs-builder changelog add --prs prs.txt \ In this example, the command creates one changelog for each pull request in the list. -#### Create changelogs from GitHub release notes [changelog-add-release-version] +### Create changelogs from GitHub release notes [changelog-add-release-version] If you have GitHub releases with automated release notes (the default format or [Release Drafter](https://github.com/release-drafter/release-drafter) format), the changelog commands can derive the PR list from those release notes with the `--release-version` option. For example: @@ -307,6 +264,18 @@ The option precedence is: CLI option > `changelog.yml` bundle section > built-in You can use the `docs-builder changelog gh-release` command as a one-shot alternative to `changelog add` and `changelog bundle` commands. The command parses the release notes, creates one changelog file per pull request found, and creates a `changelog-bundle.yaml` file — all in a single step. Refer to [](/cli/changelog/gh-release.md) -:::{note} -This command requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. Refer to [Authorization](#authorization) for details. -::: +### Product format + +The `docs-builder changelog add` has a `--products` option and the `docs-builder changelog bundle` has `--input-products` and `--output-products` options that all use the same format. + +They accept values with 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"` \ No newline at end of file From a5a3854c60ef266cc2692c03aef74f32a600a33f Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 22 Apr 2026 19:49:21 -0700 Subject: [PATCH 2/6] Remove some unnecessary examples --- docs/contribute/configure-changelogs-ref.md | 34 ++++++++++-- docs/contribute/create-changelogs.md | 61 --------------------- 2 files changed, 29 insertions(+), 66 deletions(-) diff --git a/docs/contribute/configure-changelogs-ref.md b/docs/contribute/configure-changelogs-ref.md index 1d49e0dc7d..c0cd280811 100644 --- a/docs/contribute/configure-changelogs-ref.md +++ b/docs/contribute/configure-changelogs-ref.md @@ -107,7 +107,6 @@ Controls how the `changelog add` command extracts information from PR descriptio | `extract.release_notes` | Auto-extract release notes from PR descriptions (default: `true`). | | `extract.strip_title_prefix` | Remove square-bracket prefixes from PR titles (default: `false`). | - When `extract.issues` is `true`, the system looks for patterns like "Fixes #123" in PR bodies (when you're creating changelogs from PRs) or "Fixed by #123" in issue bodies (when you're creating changelogs from issues). When `extract.release_notes` is `true`, the system looks for content like this in the PR or issue description: @@ -121,6 +120,14 @@ When `extract.release_notes` is `true`, the system looks for content like this i The extracted release note text is used in the changelog `description`. +When `extract.strip_title_prefix` is `true` and PR or issue titles have a prefix in square brackets (such as `[ES|QL]` or `[Security]`), they are automatically removed from the changelog title. +Multiple square bracket prefixes are also supported (for example `[Discover][ESQL] Title` becomes `Title`). +If a colon follows the closing bracket, it is also removed. + +:::{note} +The title cleanup only occurs when the title is derived from GitHub. If you specify `--title` explicitly, that title is used as-is without any prefix stripping. +::: + ## Filename [filename] Controls how the `changelog add` command generates changelog file names. @@ -128,14 +135,12 @@ Controls how the `changelog add` command generates changelog file names. :::{table} :widths: description - | Value | Description | | --------------------- | ------------------------------------------------------------------------------ | | `timestamp` (default) | Use Unix timestamp with title slug (for example, `1735689600-fix-search.yaml`) | | `pr` | Use the PR number (for example, `12345.yaml`) | | `issue` | Use the issue number (for example, `67890.yaml`) | - ::: ## Lifecycles [lifecycles] @@ -145,14 +150,12 @@ Specifies the allowed lifecycle values for your changelogs. :::{table} :widths: description - | Value | Description | | --------- | --------------------------------- | | `preview` | Technical preview or early access | | `beta` | Beta release | | `ga` | General availability | - ::: :::{note} @@ -182,6 +185,27 @@ Also controls how the `changelog add` command maps GitHub labels to various chan Type and subtype values must match the available values defined in [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs) and [ChangelogEntrySubtype.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntrySubtype.cs). ::: +The following example contains demonstrates some GitHub label mappings in the `pivot` section of the chaneglog configuration file: + +```yaml +pivot: + types: + # Example mappings - customize based on your label naming conventions + breaking-change: + labels: ">breaking, >bc" + bug-fix: ">bug" + enhancement: ">enhancement" + areas: + # Example mappings - customize based on your label naming conventions + Autoscaling: ":Distributed Coordination/Autoscaling" + "ES|QL": ":Search Relevance/ES|QL" + products: + 'elasticsearch': + - ":product/elasticsearch" + 'cloud-serverless': + - ":product/serverless" +``` + ## Products [products] Specifies the allowed product values and the default values used by the `changelog add` command. diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index b25b9ba482..b4cb3cc1a8 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -90,67 +90,6 @@ Some of the fields in the schema accept only a specific set of values: ## Examples -### Create a changelog with PR label mappings [example-map-label] - -You can configure label mappings in your changelog configuration file: - -```yaml -pivot: - # Keys are type names, values can be: - # - simple string: comma-separated label list (e.g., ">bug, >fix") - # - empty/null: no labels for this type - # - object: { labels: "...", subtypes: {...} } for breaking-change type only - types: - # Example mappings - customize based on your label naming conventions - breaking-change: - labels: ">breaking, >bc" - bug-fix: ">bug" - enhancement: ">enhancement" - - # Area definitions with labels - # Keys are area display names, values are label strings - # Multiple labels can be comma-separated - areas: - # Example mappings - customize based on your label naming conventions - Autoscaling: ":Distributed Coordination/Autoscaling" - "ES|QL": ":Search Relevance/ES|QL" - - # Product definitions with labels (optional) - # Keys are product spec strings; values are label strings or lists. - # A product spec string is: " [] []" - products: - 'elasticsearch': - - ":stack/elasticsearch" - 'kibana': - - ":stack/kibana" - # Include a target version if known: - # 'cloud-serverless 2025-06 ga': - # - ":cloud/serverless" -``` - -When you use the `--prs` option to derive information from a pull request, it can make use of those mappings. Similarly, when you use the `--issues` option (without `--prs`), the command derives title, type, areas, and products from the GitHub issue labels using the same mappings. - -The following example omits `--products`, so the command derives them from the PR labels: - -```sh -docs-builder changelog add \ - --prs https://github.com/elastic/elasticsearch/pull/139272 \ - --config test/changelog.yml \ - --strip-title-prefix -``` - -In this case, the changelog file derives the title, type, areas, and products from the pull request. -If none of the PR's labels match `pivot.products`, the command falls back to `products.default` or repository name inference from `--repo` (refer to [Products resolution](/cli/changelog/add.md#products-resolution) for more details). -The command also looks for patterns like `Fixes #123`, `Closes owner/repo#456`, `Resolves https://github.com/.../issues/789` in the pull request to derive its issues. Similarly, when using `--issues`, the command extracts linked PRs from the issue body (for example, "Fixed by #123"). You can turn off this behavior in either case with the `--no-extract-issues` flag or by setting `extract.issues: false` in the changelog configuration file. The `extract.issues` setting applies to both directions: issues extracted from PR bodies (when using `--prs`) and PRs extracted from issue bodies (when using `--issues`). - -The `--strip-title-prefix` option in this example means that if the PR title has a prefix in square brackets (such as `[ES|QL]` or `[Security]`), it is automatically removed from the changelog title. Multiple square bracket prefixes are also supported (for example `[Discover][ESQL] Title` becomes `Title`). If a colon follows the closing bracket, it is also removed. - -By default, `--strip-title-prefix` is disabled. You can enable it globally by setting `extract.strip_title_prefix: true` in the changelog configuration file, which will apply the prefix stripping to all `changelog add` and `changelog gh-release` commands without requiring the CLI flag. The CLI flag `--strip-title-prefix` overrides the configuration setting. - -:::{note} -The `--strip-title-prefix` option only applies when the title is derived from the PR (when `--title` is not explicitly provided). If you specify `--title` explicitly, that title is used as-is without any prefix stripping. -::: - ### Extract release notes from PR descriptions [example-extract-release-notes] When you use the `--prs` option, by default the `docs-builder changelog add` command automatically extracts text from the PR descriptions and use it in your changelog. From 8149c4f81f73f1193ed50cd798ed6ab3ab102653 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 23 Apr 2026 15:27:42 -0700 Subject: [PATCH 3/6] Clean up release note extraction details --- docs/cli/changelog/add.md | 10 +-------- docs/contribute/configure-changelogs-ref.md | 2 +- docs/contribute/create-changelogs.md | 24 +-------------------- 3 files changed, 3 insertions(+), 33 deletions(-) diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index c30be4cbd0..0a41231fd9 100644 --- a/docs/cli/changelog/add.md +++ b/docs/cli/changelog/add.md @@ -30,15 +30,7 @@ docs-builder changelog add [options...] [-h|--help] `--no-extract-release-notes` : Optional: Turn off extraction of release notes from PR or issue descriptions. -: The extractor looks for content in various formats in the PR or issue description: -: - `Release Notes: ...` -: - `Release-Notes: ...` -: - `release notes: ...` -: - `Release Note: ...` -: - `Release Notes - ...` -: - `## Release Note` (as a markdown header) -: Matched release note text is used as the changelog description (only if `--description` is not explicitly provided). The changelog title is always taken from `--title` or from the PR or issue title, not from the release note section. -: By default, the behavior is determined by the `extract.release_notes` changelog configuration setting. +: By default, the behavior is determined by the [extract.release_notes](/contribute/configure-changelogs-ref.md#extract) changelog configuration setting. `--feature-id ` : Optional: Feature flag ID diff --git a/docs/contribute/configure-changelogs-ref.md b/docs/contribute/configure-changelogs-ref.md index c0cd280811..8cb2ab5e0a 100644 --- a/docs/contribute/configure-changelogs-ref.md +++ b/docs/contribute/configure-changelogs-ref.md @@ -104,7 +104,7 @@ Controls how the `changelog add` command extracts information from PR descriptio | Setting | Description | | ---------------------------- | ------------------------------------------------------------------- | | `extract.issues` | Auto-extract linked issues/PRs from descriptions (default: `true`). | -| `extract.release_notes` | Auto-extract release notes from PR descriptions (default: `true`). | +| `extract.release_notes` | Auto-extract descriptions from GitHub (default: `true`). | | `extract.strip_title_prefix` | Remove square-bracket prefixes from PR titles (default: `false`). | When `extract.issues` is `true`, the system looks for patterns like "Fixes #123" in PR bodies (when you're creating changelogs from PRs) or "Fixed by #123" in issue bodies (when you're creating changelogs from issues). diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index b4cb3cc1a8..1e4fe4b7cf 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -44,6 +44,7 @@ If you already have automated release notes for GitHub releases, you can use the When you specify `--prs` or `--issues`, the command tries to fetch information from GitHub. It derives the title from the pull request or issue title, extracts linked references, and derives the areas, products, and type from labels (if mappings are defined in the configuration file). + To control what information is extracted, refer to the [extract](/contribute/configure-changelogs-ref.md#extract) and [pivot](/contribute/configure-changelogs-ref.md#pivot) sections of the changelog configuration file. For the most up-to-date command syntax, use the `-h` option or refer to [](/cli/changelog/add.md). @@ -90,29 +91,6 @@ Some of the fields in the schema accept only a specific set of values: ## Examples -### Extract release notes from PR descriptions [example-extract-release-notes] - -When you use the `--prs` option, by default the `docs-builder changelog add` command automatically extracts text from the PR descriptions and use it in your changelog. - -In particular, it looks for content in these formats in the PR description: - -- `Release Notes: This is the extracted sentence.` -- `Release-Notes: This is the extracted sentence.` -- `release notes: This is the extracted sentence.` -- `Release Note: This is the extracted sentence.` -- `Release Notes - This is the extracted sentence.` -- `## Release Note` (as a markdown header) - -How the extracted text is used: - -- **Release note found**: The extracted text is used as the changelog description (only if `--description` is not explicitly provided). The changelog title comes from `--title` or the PR title, not from the release note section. -- **No release note found**: No description is filled from the PR body; the title still comes from `--title` or the PR title as usual. - -:::{note} -If you explicitly provide `--title` or `--description`, those values take precedence over extracted release notes. -You can turn off the release note extraction in the changelog configuration file or by using the `--no-extract-release-notes` option. -::: - ### Control changelog creation [example-block-label] You can prevent changelog creation for certain PRs based on their labels. From b2d0b402b25881ad7a0e310f6c07f688324b3993 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 28 Apr 2026 18:16:06 -0700 Subject: [PATCH 4/6] Final edits --- docs/cli/changelog/add.md | 93 ++++++++++++++++------------ docs/cli/changelog/bundle.md | 25 +++++++- docs/contribute/bundle-changelogs.md | 3 +- docs/contribute/create-changelogs.md | 52 ++++------------ 4 files changed, 90 insertions(+), 83 deletions(-) diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index 0a41231fd9..c5874395cf 100644 --- a/docs/cli/changelog/add.md +++ b/docs/cli/changelog/add.md @@ -68,8 +68,7 @@ docs-builder changelog add [options...] [-h|--help] : 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). -: **Precedence when `--products` is not specified:** products are derived from PR/issue labels via `pivot.products` label mappings (if configured), then from `products.default` in `changelog.yml`, and finally inferred from the current git repository name. An error is raised if no products can be determined by any of these means. -: Refer to [Products resolution](#products-resolution) in the how-to guide for full details. +: For more information about the valid product and lifecycle values, go to [Product format](#product-format). `--prs ` : Optional: Pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times. @@ -126,36 +125,6 @@ docs-builder changelog add [options...] [-h|--help] : Mutually exclusive with `--use-pr-number`. : Refer to [](#filenames). -## CI auto-detection [ci-auto-detection] - -When running inside GitHub Actions, `changelog add` automatically reads the following environment variables to fill in arguments that were not provided on the command line: - -| Environment variable | Fills | Set from | -| --- | --- | --- | -| `CHANGELOG_PR_NUMBER` | `--prs` | `github.event.pull_request.number` | -| `CHANGELOG_TITLE` | `--title` | `steps.evaluate.outputs.title` | -| `CHANGELOG_DESCRIPTION` | `--description` | `steps.evaluate.outputs.description` | -| `CHANGELOG_TYPE` | `--type` | `steps.evaluate.outputs.type` | -| `CHANGELOG_PRODUCTS` | `--products` | `steps.evaluate.outputs.products` | -| `CHANGELOG_OWNER` | `--owner` | `github.repository_owner` | -| `CHANGELOG_REPO` | `--repo` | `github.event.repository.name` | - -**Precedence**: explicit CLI arguments always take priority over environment variables. Environment variables are only used when the corresponding CLI argument is not provided. - -`CHANGELOG_DESCRIPTION` has additional precedence rules related to release note extraction: - -- If `--description` is provided on the command line, it always wins. -- If `--no-extract-release-notes` is passed (or `extract.release_notes: false` is set in the changelog configuration), `CHANGELOG_DESCRIPTION` is ignored. This prevents a description that was extracted by `evaluate-pr` from being applied when extraction has been disabled. -- Otherwise, `CHANGELOG_DESCRIPTION` fills `--description` when it is not set on the command line. - -The filename strategy is controlled by the `filename` option in `changelog.yml` (defaulting to `timestamp`). Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) for details. - -This allows the CI action to invoke `changelog add` with a minimal command line: - -```sh -docs-builder changelog add --config docs/changelog.yml --output /tmp/staging --concise --strip-title-prefix -``` - ## Filenames By default, output files are named according to the `filename` strategy in `changelog.yml`: @@ -188,17 +157,30 @@ docs-builder changelog add \ **Precedence**: CLI flags (`--use-pr-number` / `--use-issue-number`) > `filename` in `changelog.yml` > default (`timestamp`). ::: -## Products resolution [products-resolution] +## Product format and resolution [product-format] + +The `--products` command option accepts values with the format `"product target lifecycle, ..."` where: + +- `product` is a product ID that exists in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required) +- `target` is the target version or date (optional) +- `lifecycle` exists in [Lifecycle.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs) (optional) + +You can further limit the possible values with the [products](/contribute/configure-changelogs-ref.md#products) and [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) options in the changelog configuration file. -When you run the `changelog add` command without the `--products` option, it resolves products in the following order: +For example: -1. **`--products` CLI option** — always takes priority. -2. **`pivot.products` label mapping** — if `pivot.products` is configured and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied. -3. **`products.default` in `changelog.yml`** — the configured default products are used. -4. **Repository name inference** — if `--repo` is specified (or `bundle.repo` is set in `changelog.yml`), the repository name is matched against known product IDs in `products.yml`. -5. **Error** — if none of the above resolves to at least one product, an error is raised. +- `"kibana 9.2.0 ga"` +- `"cloud-serverless 2025-08-05"` +- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` -Product-specific `rules.create` rules are evaluated *after* products are resolved from labels, so label-derived products correctly participate in per-product create rule checks. +The `changelog add` command resolves product values in the following order: + +1. The `--products` CLI option always takes priority. +1. If `pivot.products` is defined in the changelog configuration file and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied. +1. If `products.default` is defined in the changelog configuration file, those default products are used. +1. If `--repo` is specified (or `bundle.repo` is set in the changelog configuraiton file), the repository name is matched against known product IDs in `products.yml` and the derived value is used. + +If none of these steps yield at least one product, the command returns an error. ## Configuration checks @@ -215,3 +197,34 @@ In each of these cases where validation fails, a changelog file is not created. If the configuration file contains `rules.create` definitions and a PR or issue has a blocking label, that PR is skipped and no changelog file is created for it. For more information, refer to [Rules for creation and publishing](/contribute/configure-changelogs.md#rules). + + +## CI auto-detection [ci-auto-detection] + +When running inside GitHub Actions, `changelog add` automatically reads the following environment variables to fill in arguments that were not provided on the command line: + +| Environment variable | Fills | Set from | +| --- | --- | --- | +| `CHANGELOG_PR_NUMBER` | `--prs` | `github.event.pull_request.number` | +| `CHANGELOG_TITLE` | `--title` | `steps.evaluate.outputs.title` | +| `CHANGELOG_DESCRIPTION` | `--description` | `steps.evaluate.outputs.description` | +| `CHANGELOG_TYPE` | `--type` | `steps.evaluate.outputs.type` | +| `CHANGELOG_PRODUCTS` | `--products` | `steps.evaluate.outputs.products` | +| `CHANGELOG_OWNER` | `--owner` | `github.repository_owner` | +| `CHANGELOG_REPO` | `--repo` | `github.event.repository.name` | + +**Precedence**: explicit CLI arguments always take priority over environment variables. Environment variables are only used when the corresponding CLI argument is not provided. + +`CHANGELOG_DESCRIPTION` has additional precedence rules related to release note extraction: + +- If `--description` is provided on the command line, it always wins. +- If `--no-extract-release-notes` is passed (or `extract.release_notes: false` is set in the changelog configuration), `CHANGELOG_DESCRIPTION` is ignored. This prevents a description that was extracted by `evaluate-pr` from being applied when extraction has been disabled. +- Otherwise, `CHANGELOG_DESCRIPTION` fills `--description` when it is not set on the command line. + +The filename strategy is controlled by the `filename` option in `changelog.yml` (defaulting to `timestamp`). Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) for details. + +This allows the CI action to invoke `changelog add` with a minimal command line: + +```sh +docs-builder changelog add --config docs/changelog.yml --output /tmp/staging --concise --strip-title-prefix +``` diff --git a/docs/cli/changelog/bundle.md b/docs/cli/changelog/bundle.md index 691c64961b..ec73417875 100644 --- a/docs/cli/changelog/bundle.md +++ b/docs/cli/changelog/bundle.md @@ -93,7 +93,7 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp `--input-products ?>` : Filter by products in the format "product target lifecycle, ...". -: For more information about the valid product and lifecycle values, go to [Product format](/contribute/create-changelogs.md#product-format). +: For more information about the valid product and lifecycle values, go to [Product format](#product-format). : When specified, all three parts (product, target, lifecycle) are required but can be wildcards (`*`). Multiple comma-separated values are combined with OR: a changelog is included if it matches any of the specified product/target/lifecycle combinations. For example: - `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — include changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta @@ -122,6 +122,7 @@ The `--input-products` option determines which changelog files are gathered for `--output-products ?>` : Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...". : This value replaces information that would otherwise be derived from changelogs. +: For more information about the valid product and lifecycle values, go to [Product format](#product-format). : When `rules.bundle.products` per-product overrides are configured, `--output-products` also supplies the product IDs used to choose the **rule context product** (first alphabetically) for Mode 3. To use a different product's rules, run a separate bundle with only that product in `--output-products`. For details, refer to [Product-specific bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle-products). `--no-release-date` @@ -211,6 +212,22 @@ If you specify a file path with a different extension (not `.yml` or `.yaml`), t Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is recommended so you don't need to rely on running the command from a specific directory. ::: +## Product format + +The `changelog bundle` command has `--input-products` and `--output-products` options that accept values with 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` exists in [Lifecycle.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs) (optional) + +You can further limit the possible values with the [products](/contribute/configure-changelogs-ref.md#products) and [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) options in the changelog configuration file. + +For example: + +- `"kibana 9.2.0 ga"` +- `"cloud-serverless 2025-08-05"` +- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` + ## Repository name in bundles [changelog-bundle-repo] The repository name is stored in each bundle product entry to ensure that PR and issue links are generated correctly when the bundle is rendered. @@ -439,6 +456,7 @@ If you're using profile-based commands, they're affected by the following fields : Not used when the filter comes from a promotion report, URL list file, or `source: github_release` — in those cases the PR or issue list determines what's included and `products` is ignored. : Supports `{version}` and `{lifecycle}` placeholders that are substituted at runtime. : Example: `"elasticsearch {version} {lifecycle}"` +: Refer to [](#product-format). :::{note} The `products` field determines which changelog files are gathered for consideration. **`rules.bundle` still applies** afterward (see the note under [`--input-products`](#options)). Input stage and bundle filtering stage are conceptually separate. @@ -457,6 +475,7 @@ The `products` field determines which changelog files are gathered for considera : The `{lifecycle}` placeholder is substituted at runtime with the inferred lifecycle. For `source: github_release` profiles this comes from the release tag suffix. For standard profiles it comes from the version argument. Refer to [](#changelog-bundle-standard-profile-lifecycle) and [](#changelog-bundle-github-release-profile) for details. : If you omit lifecycle from the pattern (for example, `"elasticsearch {version}"`), the lifecycle field is omitted from the products array entirely. : Example: `"elasticsearch {version} {lifecycle}"` or `"elasticsearch {version} ga"` to hardcode GA regardless of tag. +: Refer to [](#product-format). `repo` : Optional. The GitHub repository name written to each product entry in the bundle. Used by the `{changelog}` directive to generate correct PR/issue links. Only needed when the product ID doesn't match the GitHub repository name. Overrides `bundle.repo` when set. Required when `source: github_release` is used and no `bundle.repo` default is set. @@ -481,7 +500,7 @@ If your configuration file defines a standard profile (that is to say, not a Git | `9.2.0-alpha.1` | `preview` | | `9.2.0-preview.1` | `preview` | -For more information about acceptable product and lifecycle values, go to [Product format](/contribute/create-changelogs.md#product-format). +For more information about acceptable product and lifecycle values, go to [Product format](#product-format). You can invoke those profiles with commands like this: @@ -664,4 +683,4 @@ gh-release: ``` By default all changelogs that match PRs in the GitHub release notes are included in the bundle. -To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules). \ No newline at end of file +To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules). diff --git a/docs/contribute/bundle-changelogs.md b/docs/contribute/bundle-changelogs.md index a1ce24c50c..facc3071ce 100644 --- a/docs/contribute/bundle-changelogs.md +++ b/docs/contribute/bundle-changelogs.md @@ -261,7 +261,7 @@ docs-builder changelog bundle \ --input-products "cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta" <1> ``` -1. Include all changelogs that have the `cloud-serverless` product identifier with target dates of either December 2 2025 (lifecycle `ga`) or December 6 2025 (lifecycle `beta`). For more information about product values, refer to [Product format](/contribute/create-changelogs.md#product-format). +1. Include all changelogs that have the `cloud-serverless` product identifier with target dates of either December 2 2025 (lifecycle `ga`) or December 6 2025 (lifecycle `beta`). For more information about product values, refer to [Product format](/cli/changelog/bundle.md#product-format). You can use wildcards in any of the three parts: @@ -594,3 +594,4 @@ docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run ``` For full option details, go to [](/cli/changelog/remove.md). + diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index 1e4fe4b7cf..34251447b3 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -82,31 +82,24 @@ Changelog files use the following schema: For content guidelines, go to [Changelogs](https://www.elastic.co/docs/contribute-docs/content-types/changelogs). -:::{note} +:::{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). - 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. + +You can further limit the possible values with the [products](/contribute/configure-changelogs-ref.md#products) and [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) options in the changelog configuration file. ::: ## Examples ### Control changelog creation [example-block-label] -You can prevent changelog creation for certain PRs based on their labels. - -If you run the `docs-builder changelog add` command with the `--prs` option and a PR has a blocking label for any of the resolved products (from `--products`, `pivot.products` label mapping, or `products.default`), that PR will be skipped and no changelog file will be created for it. -A warning message will be emitted indicating which PR was skipped and why. - -For example, your configuration file can contain a `rules` section like this: +You can prevent changelog creation for PRs based on their labels. +For example, your configuration file can contain a `rules.create` section like this: ```yaml rules: - # Global match default for multi-valued fields (labels, areas). - # any (default) = match if ANY item matches the list - # all = match only if ALL items match the list - # match: any - # Create — controls which PRs generate changelogs. create: # Labels that block changelog creation (comma-separated string) @@ -121,15 +114,13 @@ Those settings affect commands with the `--prs` or `--issues` options, for examp ```sh docs-builder changelog add --prs "1234, 5678" \ - --products "cloud-serverless" \ - --owner elastic --repo elasticsearch \ - --config test/changelog.yml + --products "cloud-serverless" ``` If PR 1234 has the `>non-issue` or `>test` labels, it will be skipped and no changelog will be created. If PR 5678 does not have any blocking labels, a changelog is created. -You can also use **include** mode instead of **exclude** mode. +Alternatively, you can define `rules.create.include` labels. For example, to only create changelogs for PRs with specific labels: ```yaml @@ -138,6 +129,8 @@ rules: include: "@Public, @Notable" ``` +For more information about these changelog configuration settings, refer to [](/contribute/configure-changelogs-ref.md#rules-create). + ### Create changelogs from a file [example-file-add] You can create multiple changelogs in a single command by providing a newline-delimited file that contains pull requests or issues. @@ -152,8 +145,7 @@ EOF # Use the file with --prs docs-builder changelog add --prs prs.txt \ - --products "elasticsearch 9.2.0 ga" \ - --config test/changelog.yml + --products "elasticsearch 9.2.0 ga" ``` In this example, the command creates one changelog for each pull request in the list. @@ -164,9 +156,7 @@ If you have GitHub releases with automated release notes (the default format or For example: ```sh -docs-builder changelog add \ - --release-version v1.34.0 \ - --repo apm-agent-dotnet --owner elastic +docs-builder changelog add --release-version v1.34.0 ``` This command creates one changelog file per PR found in the `v1.34.0` GitHub release notes. @@ -175,24 +165,8 @@ For example, a tag of `v1.34.0` in the `apm-agent-dotnet` repo creates changelog :::{note} `--release-version` requires `--repo` (or `bundle.repo` set in `changelog.yml`) and is mutually exclusive with `--prs` and `--issues`. -The option precedence is: CLI option > `changelog.yml` bundle section > built-in default. This applies to `--repo`, `--owner`, and `--output` for all `changelog add` modes. +The option precedence is: CLI option > `changelog.yml` bundle section > built-in default. ::: You can use the `docs-builder changelog gh-release` command as a one-shot alternative to `changelog add` and `changelog bundle` commands. -The command parses the release notes, creates one changelog file per pull request found, and creates a `changelog-bundle.yaml` file — all in a single step. Refer to [](/cli/changelog/gh-release.md) - -### Product format - -The `docs-builder changelog add` has a `--products` option and the `docs-builder changelog bundle` has `--input-products` and `--output-products` options that all use the same format. - -They accept values with 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"` \ No newline at end of file +The command parses the release notes, creates one changelog file per pull request found, and creates a `changelog-bundle.yaml` file — all in a single step. Refer to [](/cli/changelog/gh-release.md) \ No newline at end of file From 39a6761d31d3199b53c5640160d657d11ac44334 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 28 Apr 2026 18:23:31 -0700 Subject: [PATCH 5/6] Update docs/contribute/configure-changelogs-ref.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/contribute/configure-changelogs-ref.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/contribute/configure-changelogs-ref.md b/docs/contribute/configure-changelogs-ref.md index 8cb2ab5e0a..b1d768d469 100644 --- a/docs/contribute/configure-changelogs-ref.md +++ b/docs/contribute/configure-changelogs-ref.md @@ -185,8 +185,7 @@ Also controls how the `changelog add` command maps GitHub labels to various chan Type and subtype values must match the available values defined in [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs) and [ChangelogEntrySubtype.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntrySubtype.cs). ::: -The following example contains demonstrates some GitHub label mappings in the `pivot` section of the chaneglog configuration file: - +The following example demonstrates some GitHub label mappings in the `pivot` section of the changelog configuration file: ```yaml pivot: types: From 4132938307aa89db7fc7e867a40037dd4c5bc31e Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 28 Apr 2026 18:24:12 -0700 Subject: [PATCH 6/6] Update docs/cli/changelog/add.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/cli/changelog/add.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index c5874395cf..d90e8ed8e5 100644 --- a/docs/cli/changelog/add.md +++ b/docs/cli/changelog/add.md @@ -178,7 +178,7 @@ The `changelog add` command resolves product values in the following order: 1. The `--products` CLI option always takes priority. 1. If `pivot.products` is defined in the changelog configuration file and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied. 1. If `products.default` is defined in the changelog configuration file, those default products are used. -1. If `--repo` is specified (or `bundle.repo` is set in the changelog configuraiton file), the repository name is matched against known product IDs in `products.yml` and the derived value is used. +1. If `--repo` is specified (or `bundle.repo` is set in the changelog configuration file), the repository name is matched against known product IDs in `products.yml` and the derived value is used. If none of these steps yield at least one product, the command returns an error.