diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index 23fe870fe9..d90e8ed8e5 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 @@ -76,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. @@ -123,10 +114,90 @@ 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). + +## 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`). +::: + +## 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. + +For example: + +- `"kibana 9.2.0 ga"` +- `"cloud-serverless 2025-08-05"` +- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` + +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 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. + +## Configuration checks + +By default, the command checks the following path for a configuration file: `docs/changelog.yml`. +You can specify a different path with the `--config` command option. + +If a configuration file exists, the command validates its values before generating changelog files: + +- If the configuration file contains `lifecycles`, `products`, `subtype`, or `type` values that don't match the values in `ChangelogEntryType.cs`, `ChangelogEntrySubtype.cs`, or `Lifecycle.cs`, validation fails. +- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails. +- If the configuration file contains `lifecycles` or `products` values that are a subset of the available values and you try to create a changelog with values outside that subset, validation fails. + +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] @@ -157,31 +228,3 @@ 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 ``` - -## Products resolution [products-resolution] - -When you run the `changelog add` command without the `--products` option, it resolves products in the following order: - -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. - -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. - -## Configuration checks - -By default, the command checks the following path for a configuration file: `docs/changelog.yml`. -You can specify a different path with the `--config` command option. - -If a configuration file exists, the command validates its values before generating changelog files: - -- If the configuration file contains `lifecycles`, `products`, `subtype`, or `type` values that don't match the values in `ChangelogEntryType.cs`, `ChangelogEntrySubtype.cs`, or `Lifecycle.cs`, validation fails. -- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails. -- If the configuration file contains `lifecycles` or `products` values that are a subset of the available values and you try to create a changelog with values outside that subset, validation fails. - -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). 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/configure-changelogs-ref.md b/docs/contribute/configure-changelogs-ref.md index 1d49e0dc7d..b1d768d469 100644 --- a/docs/contribute/configure-changelogs-ref.md +++ b/docs/contribute/configure-changelogs-ref.md @@ -104,10 +104,9 @@ 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). 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,26 @@ 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 demonstrates some GitHub label mappings in the `pivot` section of the changelog 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/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..34251447b3 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -1,238 +1,105 @@ # 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 -:::: -::: - -:::{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. -::: - -## Create changelog files [changelog-add] - -You can use the `docs-builder changelog add` command to create a changelog file. - -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"). +This page describes how to create these files both from the [command line](#command-line) and from [GitHub actions](#github-actions). -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. +## Before you begin -:::{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 +Create a changelog configuration file to define all the default behavior and PR label mappings. +Refer to [](/contribute/configure-changelogs.md). -When automated via the [changelog GitHub Actions](https://github.com/elastic/docs-actions/tree/main/changelog), changelog creation is a two-step process: +## Create changelog files from command line [command-line] -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. +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. -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. +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). -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). + 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. -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: - -- `"kibana 9.2.0 ga"` -- `"cloud-serverless 2025-08-05"` -- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` - -### Filenames - -The `docs-builder changelog add` command names generated files 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. | - -Set the strategy in your changelog configuration file: - -```yaml -filename: timestamp -``` - -Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) for full documentation. - -You can override the configured strategy per invocation with the `--use-pr-number` or `--use-issue-number` CLI flags: - -```sh -docs-builder changelog add \ - --prs https://github.com/elastic/elasticsearch/pull/137431 \ - --products "elasticsearch 9.2.3" \ - --use-pr-number - -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. +## Create changelogs from GitHub actions [github-actions] -**Precedence**: CLI flags (`--use-pr-number` / `--use-issue-number`) > `filename` in `changelog.yml` > default (`timestamp`). -::: - -### Examples - -#### Create a changelog for multiple products [example-multiple-products] - -```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> -``` - -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. - -#### Create a changelog with PR label mappings [example-map-label] +When automated via the [changelog GitHub Actions](https://github.com/elastic/docs-actions/tree/main/changelog), changelog creation is a two-step process: -You can configure label mappings in your changelog configuration file: +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. -```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" -``` +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. -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. +Refer to [CI auto-detection](/cli/changelog/add.md#ci-auto-detection) for the full list of environment variables and precedence rules. -The following example omits `--products`, so the command derives them from the PR labels: +## Review the content [review] -```sh -docs-builder changelog add \ - --prs https://github.com/elastic/elasticsearch/pull/139272 \ - --config test/changelog.yml \ - --strip-title-prefix -``` +1. Find the files that were created by the command or GitHub action. -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`). + 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). -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. +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. -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. +Changelog files use the following schema: -:::{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. +:::{dropdown} Changelog schema +::::{include} /contribute/_snippets/changelog-fields.md +:::: ::: -#### 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. +For content guidelines, go to [Changelogs](https://www.elastic.co/docs/contribute-docs/content-types/changelogs). -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: +:::{important} +Some of the fields in the schema accept only a specific set of values: -- **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. +- 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. -:::{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. +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. ::: -#### Control changelog creation [example-block-label] - -You can prevent changelog creation for certain PRs based on their labels. +## Examples -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. +### Control changelog creation [example-block-label] -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) @@ -247,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 @@ -264,7 +129,9 @@ rules: include: "@Public, @Notable" ``` -#### Create changelogs from a file [example-file-add] +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. For example: @@ -278,21 +145,18 @@ 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. -#### 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: ```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. @@ -301,12 +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) - -:::{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. -::: +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