From e4943f67af77de23c5e7aa44865230e088bc834e Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 29 Apr 2026 19:51:05 -0700 Subject: [PATCH 1/6] Edit changelog bundle docs --- config/changelog.example.yml | 2 +- docs/cli/changelog/add.md | 2 +- docs/cli/changelog/bundle.md | 219 +------- docs/cli/changelog/gh-release.md | 2 +- docs/cli/changelog/remove.md | 4 +- docs/contribute/bundle-changelogs.md | 582 +++++++++++++------- docs/contribute/configure-changelogs-ref.md | 110 ++-- docs/contribute/configure-changelogs.md | 41 +- docs/contribute/create-changelogs.md | 17 +- docs/syntax/changelog.md | 5 +- 10 files changed, 493 insertions(+), 491 deletions(-) diff --git a/config/changelog.example.yml b/config/changelog.example.yml index 859dbe2a4..4288edd5b 100644 --- a/config/changelog.example.yml +++ b/config/changelog.example.yml @@ -151,7 +151,7 @@ pivot: # - Comma-separated string: "value1, value2, value3" # - YAML list: [value1, value2, value3] # -# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs.md#rules). +# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/contribute/configure-changelogs-ref#rules). rules: # match: any diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index d90e8ed8e..2368afb5a 100644 --- a/docs/cli/changelog/add.md +++ b/docs/cli/changelog/add.md @@ -196,7 +196,7 @@ If a configuration file exists, the command validates its values before generati 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). +For more information, refer to [](/contribute/create-changelogs.md#rules). ## CI auto-detection [ci-auto-detection] diff --git a/docs/cli/changelog/bundle.md b/docs/cli/changelog/bundle.md index ec7341787..8f1c0452a 100644 --- a/docs/cli/changelog/bundle.md +++ b/docs/cli/changelog/bundle.md @@ -228,6 +228,8 @@ For example: - `"cloud-serverless 2025-08-05"` - `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"` +If you use `"* * *"` in the `--input-products` command option or `bundle.profiles..products` configuration setting, it's equivalent to the `--all` command option. + ## 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. @@ -268,57 +270,6 @@ If no `repo` is set at any level, the product ID is used as a fallback for link This may result in broken links if the product ID doesn't match the GitHub repository name (for example, `cloud-serverless` product ID in the `elasticsearch` repo). ::: -## Rules for filtered bundles [changelog-bundle-rules] - -The `rules.bundle` section in the changelog configuration file lets you filter entries during bundling. It applies to both `changelog bundle` and `changelog gh-release`, after entries are matched by the primary filter (`--prs`, `--issues`, `--all`, **`--input-products`**, and so on) and before the bundle is written. - -Which `rules.bundle` fields take effect depends on the bundle rule modes (no filtering, global rules against each changelog’s content, or per-product rule context). Input stage (gathering entries) and bundle filtering stage (filtering for output) are conceptually separate. For more information, refer to [bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). - -The following fields are supported: - -`exclude_products` -: A product ID or list of product IDs to exclude from the bundle. Cannot be combined with `include_products`. - -`include_products` -: A product ID or list of product IDs to include in the bundle (all others are excluded). Cannot be combined with `exclude_products`. - -`match_products` -: Match mode for the product filter (`any`, `all`, or `conjunction`). Inherits from `rules.match` when not specified. - -`exclude_types` -: A changelog type or list of types to exclude from the bundle. - -`include_types` -: Only changelogs with these types are kept; all others are excluded. - -`exclude_areas` -: A changelog area or list of areas to exclude from the bundle. - -`include_areas` -: Only changelogs with these areas are kept; all others are excluded. - -`match_areas` -: Match mode for the area filter (`any`, `all`, or `conjunction`). Inherits from `rules.match` when not specified. - -`products` -: Per-product filter overrides for **all filter types** (product, type, area). Keys are product IDs (or comma-separated lists). -: When this map is **non-empty**, the bundler uses **per-product rule context** mode: global `rules.bundle` product/type/area fields are **not** used for filtering (repeat constraints under each product key if you still need them). -: For details, refer to [Bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). - -```yaml -rules: - bundle: - exclude_products: cloud-enterprise - exclude_types: deprecation - exclude_areas: - - Internal - products: - cloud-serverless: - include_areas: - - "Search" - - "Monitoring" -``` - ## PR and issue link allowlist [link-allowlist] A changelog in a public repository might contain links to pull requests or issues in repositories that should not appear in published documentation. @@ -354,7 +305,7 @@ docs-builder changelog bundle \ ``` By default all changelogs that match PRs in the promotion report are included in the bundle. -To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules). +To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. ### Bundle by GitHub release [changelog-bundle-release-version] @@ -390,7 +341,7 @@ docs-builder changelog bundle \ ::: 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). +To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. ### Bundle with description @@ -440,55 +391,13 @@ When the bundle is rendered (by the `changelog render` command or `{changelog}` ## Profile-based examples -When the changelog configuration file defines `bundle.profiles`, you can use those profiles with the `changelog bundle` command. +When the changelog configuration file defines [bundle.profiles](/contribute/configure-changelogs-ref.md#bundle-profiles), you can use those profiles with the `changelog bundle` command. -### Profile configuration fields [changelog-bundle-profile-config] +Refer to [](/contribute/bundle-changelogs.md#create-profiles) for examples. -If you're using profile-based commands, they're affected by the following fields in the `bundle.profiles` section of the changelog configuration file: +### Lifecycle inference [lifecycle-inference] -`source` -: Optional. When set to `github_release`, the PR list is fetched automatically from the GitHub release identified by the version argument. Requires `repo` to be set at the profile or `bundle` level. Mutually exclusive with `products`. -: Example: `source: github_release` - -`products` -: Required when filtering by product metadata (equivalent to the `--input-products` command option). -: The value `"* * *"` is equivalent to the `--all` command option. -: 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. -::: - -`output` -: Optional. The output filename pattern for the bundle file. Supports `{version}` and `{lifecycle}` placeholders. -: When not set, the output path falls back in order to: `bundle.output_directory/changelog-bundle.yaml` (if `bundle.output_directory` is configured), then `changelog-bundle.yaml` in the input directory. -: Setting this is recommended so each profile produces a distinctly named file rather than overwriting the default. -: Example: `"elasticsearch-{version}.yaml"` - -`output_products` -: Optional. Overrides the products array written to the bundle output. Supports `{version}` and `{lifecycle}` placeholders. -: When **not set**, the products array is derived from the individual changelog files matched by the filter. This often produces multiple product entries (one per unique product/target/lifecycle combination across all matched files), which may not reflect a single clean release identity. -: When **set**, the products array in the bundle is exactly the value you specify, replacing anything that would be derived from the matched changelogs. Use this to publish a single, authoritative product entry with a specific version and lifecycle. -: 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. -: Example: `repo: elasticsearch`. - -`owner` -: Optional. The GitHub owner written to each product entry in the bundle. Overrides `bundle.owner` when set. -: Example: `owner: elastic` - -`hide_features` -: Optional. Feature IDs to mark as hidden in the bundle output (string or list). When the bundle is rendered, entries with matching `feature-id` values are commented out. - -### Lifecycle inference for standard profiles [changelog-bundle-standard-profile-lifecycle] +#### Standard profiles If your configuration file defines a standard profile (that is to say, not a GitHub release profile), the lifecycle is inferred from the version string you pass as the second argument: @@ -551,114 +460,9 @@ bundle: ``` ::: -### Bundle by product - -You can create profiles that are equivalent to the `--input-products` filter option, that is to say the bundle will contain only changelogs with matching `products`. -For example: +#### GitHub release profiles -```yaml -bundle: - # Input directory containing changelog YAML files - directory: docs/changelog - # Output directory for bundles - output_directory: docs/releases - # Whether to resolve (copy contents) by default - resolve: true - repo: elasticsearch <1> - owner: elastic - profiles: - # Collect all changelogs - release-all: - products: "* * *" <2> - output: "all.yaml" - # Find changelogs with any lifecycle and a partial date - serverless-monthly: - products: "cloud-serverless {version}-* *" <3> - output: "serverless-{version}.yaml" - output_products: "cloud-serverless {version}" - - # Find changelogs with a specific lifecycle - elasticsearch-ga-only: - products: "elasticsearch {version} ga" <4> - output: "elasticsearch-{version}.yaml" - - # Infer the lifecycle from the version - elasticsearch-release: - hide_features: <5> - - feature-flag-1 - - feature-flag-2 - products: "elasticsearch {version} {lifecycle}" <6> - output: "elasticsearch-{version}.yaml" - output_products: "elasticsearch {version}" -``` - -1. Bundle-level defaults that apply to all profiles. Individual profiles can override these. -2. Collects all changelogs from the `directory`. This is equivalent to the `--all` command. -3. Collects any changelogs that have `product: cloud-serverless`, any lifecycle, and the date partially specified in the command. This is equivalent to the `--input-products` command option's support for wildcards. -4. Collects any changelogs that have `product: elasticsearch`, `lifecycle: ga`, and the version specified in the command. -5. Adds a `hide-features` array in the bundle. This is equivalent to the `--hide-features` command option. -6. In this case, the lifecycle is inferred from the version string passed as the second command argument (for example, `9.2.0-beta.1` → `beta`). - -`output_products: "elasticsearch {version} {lifecycle}"` produces a single, authoritative product entry in the bundle derived from the release tag — for example, tag `v9.2.0` gives `elasticsearch 9.2.0 ga` and tag `v9.2.0-beta.1` gives `elasticsearch 9.2.0 beta`. Without `output_products`, the bundle products array is instead derived from the matched changelog files' own `products` fields, which is the consistent fallback for all profile types. Set `output_products` when you need a single clean product entry that reflects the release identity rather than the diverse metadata across individual changelog files. - -:::{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. -::: - -For profiles that use static patterns (without `{version}` or `{lifecycle}` placeholders), the second argument is still required but serves no functional purpose. You can pass any placeholder value. For example: - -```sh -# Profile with static patterns - second argument unused but required -docs-builder changelog bundle release-all '*' -docs-builder changelog bundle release-all 'unused' -docs-builder changelog bundle release-all 'none' -``` - -If you are using the `{version}` placeholder in the `output_products` or `output` fields, you must provide an appropriate value even though it's not used by the `products` filter. - -### Bundle by report or URL list [profile-bundle-report-examples] - -You can also create profiles that are equivalent to the `--prs`, `--issues`, and `--report` filter options. -That is to say you can create bundles that contain only changelogs with matching `prs` or `issues`. -For example: - -```yaml -bundle: - repo: elasticsearch <1> - owner: elastic - profiles: - # Find changelogs that match a list of PRs - serverless-report: <2> - output: "serverless-{version}.yaml" - output_products: "cloud-serverless {version}" -``` - -1. Bundle-level defaults that apply to all profiles. Individual profiles can override these. -2. If a profile is intended for use with a promotion report or a newline delimited file that lists the issues or pull requests, it does not need a `products` filter. If the `output` and `output_products` are omitted, the default path and file names are used. This example shows how you can use a `{version}` variable to customize the bundle's filename and product metadata. - -By default all changelogs that match PRs or issues in the list or report are included in the bundle. -To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules). - -### Bundle by GitHub release profiles [changelog-bundle-github-release-profile] - -To make bundling by GitHub release more easily repeatable, create a profile with `source: github_release` in your changelog configuration file. -For example: - -```yaml -bundle: - profiles: - # Fetch the PR list directly from a GitHub release - agent-gh-release: - source: github_release <1> - repo: apm-agent-dotnet <2> - output: "agent-{version}.yaml" - output_products: "apm-agent-dotnet {version} {lifecycle}" -``` - -1. Instead of filtering pre-existing changelog files by product, this profile fetches the PR list from the GitHub release notes for the given version. Mutually exclusive with `products`. -2. The repository to fetch the release from. Overrides `bundle.repo` for this profile. - -For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is inferred from the **release tag** returned by GitHub (not the argument you pass to the command). +For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is inferred from the release tag returned by GitHub (not the argument you pass to the command). This means the pre-release suffix on the tag drives the lifecycle value: | Release tag | `{version}` | `{lifecycle}` | @@ -682,5 +486,4 @@ gh-release: output_products: "apm-agent-dotnet {version} preview" ``` -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 diff --git a/docs/cli/changelog/gh-release.md b/docs/cli/changelog/gh-release.md index fb4eab371..f21086456 100644 --- a/docs/cli/changelog/gh-release.md +++ b/docs/cli/changelog/gh-release.md @@ -63,7 +63,7 @@ The product, target version, and lifecycle are inferred automatically from the r ## Configuration The `rules.bundle` section of your `changelog.yml` applies to bundles created by this command (after changelog files are gathered from the release). -For details, refer to [Rules for filtered bundles](/cli/changelog/bundle.md#changelog-bundle-rules). +For details, refer to [](/contribute/configure-changelogs-ref.md#rules-bundle). ## Examples diff --git a/docs/cli/changelog/remove.md b/docs/cli/changelog/remove.md index ddaa310ac..bdcfcbe37 100644 --- a/docs/cli/changelog/remove.md +++ b/docs/cli/changelog/remove.md @@ -223,7 +223,7 @@ You can remove the matching changelogs with: docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run ``` -This removes changelogs for `elasticsearch 9.2.0 ga` — the same set that `docs-builder changelog bundle elasticsearch-release 9.2.0` would include. The lifecycle is inferred from the version string: `9.2.0` → `ga`, `9.2.0-beta.1` → `beta`. Refer to [Lifecycle inference for standard profiles](/cli/changelog/bundle.md#changelog-bundle-standard-profile-lifecycle) for details. +This removes changelogs for `elasticsearch 9.2.0 ga` — the same set that `docs-builder changelog bundle elasticsearch-release 9.2.0` would include. The lifecycle is inferred from the version string: `9.2.0` → `ga`, `9.2.0-beta.1` → `beta`. Refer to [](/cli/changelog/bundle.md#lifecycle-inference) for details. ### Remove by report or URL list @@ -283,4 +283,4 @@ docs-builder changelog remove agent-gh-release 1.34.0 --dry-run The `repo` and `owner` used to identify the release follow the same precedence as bundling: profile-level `repo`/`owner` override `bundle.repo`/`bundle.owner`, which in turn override the default owner `elastic`. ::: -For the full list of profile configuration fields, go to [Profile configuration fields](/cli/changelog/bundle.md#changelog-bundle-profile-config). +For the full list of profile configuration fields, go to [](/contribute/configure-changelogs-ref.md#bundle-profiles). diff --git a/docs/contribute/bundle-changelogs.md b/docs/contribute/bundle-changelogs.md index facc3071c..26e66cac7 100644 --- a/docs/contribute/bundle-changelogs.md +++ b/docs/contribute/bundle-changelogs.md @@ -1,140 +1,377 @@ # Bundle changelogs -You can use the `docs-builder changelog bundle` command to create a YAML file that lists multiple changelogs. -The command has two modes of operation: you can specify all the command options or you can define "profiles" in the changelog configuration file. -The latter is more convenient and consistent for repetitive workflows. -For up-to-date details, use the `-h` option or refer to [](/cli/changelog/bundle.md). +You can use `docs-builder changelog` commands to created consolidated data files ("release bundles") that list all the notable changes associated with a particular release. +These files are ultimately used to generate release documentation. -The command supports two mutually exclusive usage modes: +This page describes how to create these files from the command line. +For details about the equivalent GitHub action, refer to the [docs-actions README](https://github.com/elastic/docs-actions/blob/main/changelog/README.md#bundling-changelogs). -- **Option-based** — you provide filter and output options directly on the command line. -- **Profile-based** — you specify a named profile from your `changelog.yml` configuration file. +## Before you begin -You cannot mix these two modes: when you use a profile name, no filter or output options are accepted on the command line. +1. Create a changelog configuration file to define all the default behavior and optional profiles and rules. Refer to [](/contribute/configure-changelogs.md). +1. Create changelogs that describe all the notable changes. Refer to [](/contribute/create-changelogs.md). -:::{tip} -Alternatively, if you already have automated release notes for GitHub releases, you can use the `docs-builder changelog gh-release` command to create changelog files and a bundle from your GitHub release notes. Refer to [](/cli/changelog/gh-release.md). +## Identify your source of truth + +To have accurate release notes, there must be a definitive source of truth for what was shipped in each release. +This is a superset of what will appear in the documentation. + +The source of truth can be: + +- a list of GitHub pull requests +- a list of GitHub issues +- a buildkite promotion report (which contains a list of PRs) +- automated release notes for GitHub releases +- all changelog files that exist in a specific folder +- all changelog files that match specific products, versions, and lifecycles + +Deriving the source of truth from the contents of a folder or from the metadata in changelogs are the least accurate options (unless you have additional processes to confirm the validity of that information). +It is recommended to use lists that are generated as part of your release coordination activities. +Consider your options carefully and discuss with your docs team if necessary. + +:::{important} +Not everything that was shipped will have a changelog. +For example, you can configure [rules](/contribute/create-changelogs.md#rules) that control changelog creation for work that's not publicly notable or spans multiple PRs. + +Your release workflow should not assume there will be a one-to-one mapping between what was shipped and what will be documented. ::: -## Option-based bundling [changelog-bundle-options] +## Create profiles -You can specify only one of the following filter options: +The [changelog bundle](/cli/changelog/bundle.md) command has two modes of operation. +You can: -- `--all`: Include all changelogs from the directory. -- `--input-products`: Include changelogs for the specified products. Refer to [Filter by product](#changelog-bundle-product). -- `--prs`: Include changelogs for the specified pull request URLs, or a path to a newline-delimited file. When using a file, every line must be a fully-qualified GitHub URL such as `https://github.com/owner/repo/pull/123`. Go to [Filter by pull requests](#changelog-bundle-pr). -- `--issues`: Include changelogs for the specified issue URLs, or a path to a newline-delimited file. When using a file, every line must be a fully-qualified GitHub URL such as `https://github.com/owner/repo/issues/123`. Go to [Filter by issues](#changelog-bundle-issues). -- `--release-version`: Bundle changelogs for the pull requests in GitHub release notes. Refer to [Bundle by GitHub release](#changelog-bundle-release-version). -- `--report`: Include changelogs whose pull requests appear in a promotion report. Accepts a URL or a local file path to an HTML report. +- specify all the command options every time you run the command, or +- define "profiles" in the changelog configuration file -`rules.bundle` in `changelog.yml` is **not** mutually exclusive with these options: it runs as a **second stage** after the primary filter matches entries (for example, `--input-products` gathers changelogs, then global or per-product bundle rules may exclude some). The only mutually exclusive pairing is **profile-based** versus **option-based** invocation. See [bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). +The latter method is more convenient and consistent for repetitive workflows, therefore it's the recommended method described here. -By default, the output file contains only the changelog file names and checksums. -To change this behavior, set `bundle.resolve` to `true` in the changelog configuration file or use the `--resolve` command option. +For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) and [](/contribute/configure-changelogs-ref.md). -:::{tip} -If you plan to use [changelog directives](/contribute/publish-changelogs.md#changelog-directive), it is recommended to pull all of the content from each changelog into the bundle; otherwise you can't delete your changelogs. -If you likewise want to regenerate your [Asciidoc or Markdown files](/contribute/publish-changelogs.md#render-changelogs) after deleting your changelogs, it's only possible if you have "resolved" bundles. +:::{note} +You must create profiles that match your chosen source of truth. ::: - +### Bundle by report or URL list [profile-url] + +If the source of truth for what was shipped in each release is: + +- a list of GitHub pull requests +- a list of GitHub issues +- a buildkite promotion report (which contains a list of PRs) + +... your profile does not have any mandatory settings. +However it's a good idea to define the [basic bundle settings](/contribute/configure-changelogs-ref.md#bundle-basic) and the [profile settings](/contribute/configure-changelogs-ref.md#bundle-profiles) for the output filename and output products. +For example: + +```yaml +bundle: + directory: docs/changelog # The directory that contains changelog files. + output_directory: docs/releases # The directory that contains changelog bundles. + repo: elasticsearch # The default repository for PR and issue links. + owner: elastic # The default repository owner for PR and issue links. + profiles: + # Find changelogs that match a list of PRs + serverless-report: + output: "serverless-{version}.yaml" <1> + output_products: "cloud-serverless {version}" <2> + elasticsearch-report: + output: "elasticsearch-{version}.yaml" + output_products: "elasticsearch {version} {lifecycle}" +``` + +<1> If the `output` and `output_products` are omitted, the default path and file names are used. This example shows how you can use a `{version}` variable to customize the bundle's filename. +<2> You can likewise set the bundle's product metadata, which affects the rules that are applied and the product and version titles that ultimately appear in the documentation. -## Profile-based bundling [changelog-bundle-profile] +### Bundle by GitHub releases [profile-gh-release] -If your `changelog.yml` configuration file defines `bundle.profiles`, you can run a bundle by profile name instead of supplying individual options: +If you have automated GitHub release notes, the `changelog bundle` command can fetch the release from GitHub, parse PR references from the release notes, and uses them as the bundle filter. +Only automated GitHub release notes (the default format or [Release Drafter](https://github.com/release-drafter/release-drafter) format) are supported at this time. + +Your profile must contain `source: github_release`. +It's also a good idea to include the [basic bundle settings](/contribute/configure-changelogs-ref.md#bundle-basic) and the [profile settings](/contribute/configure-changelogs-ref.md#bundle-profiles) for the output filename and output products. +For example: + +```yaml +bundle: + profiles: + agent-gh-release: + source: github_release <1> + repo: apm-agent-dotnet + owner: elastic + output: "agent-{version}.yaml" + output_products: "apm-agent-dotnet {version} {lifecycle}" <2> +``` + +1. This profile fetches the PR list from the GitHub release notes for the version tag specified in the command. +2. For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is inferred from the release tag returned by GitHub (not the argument you pass to the command). For example, if the release tag is `v1.34.1-preview.1` the lifecycle is `preview`. Refer to [](/cli/changelog/bundle.md#lifecycle-inference) for more details. + +### Bundle by folder or changelog product + +If the source of truth for what was shipped in each release is: + +- the `products` information that exists in each changelog +- all changelog files that exist in a specific folder + +... you must include `products` in your profile. +For example: + +```yaml +bundle: + directory: docs/changelog + output_directory: docs/releases + resolve: true + repo: elasticsearch + owner: elastic + profiles: + # Collect all changelogs + release-all: + products: "* * *" <1> + output: "all.yaml" + # Find changelogs with any lifecycle and a partial date + serverless-monthly: + products: "cloud-serverless {version}-* *" <2> + output: "serverless-{version}.yaml" + output_products: "cloud-serverless {version}" + # Find changelogs with a specific lifecycle + elasticsearch-ga-only: + products: "elasticsearch {version} ga" <3> + output: "elasticsearch-{version}.yaml" + # Infer the lifecycle from the version + elasticsearch-release: + products: "elasticsearch {version} {lifecycle}" <4> + output: "elasticsearch-{version}.yaml" + output_products: "elasticsearch {version}" +``` + +1. This profile collects all changelogs from the `directory`. +2. This profile collects any changelogs that have `product: cloud-serverless`, any lifecycle, and the date partially specified in the command. +3. This profile collects any changelogs that have `product: elasticsearch`, `lifecycle: ga`, and the version specified in the command. +4. In this case, the lifecycle is inferred from the version specified in the command. For example, if the version is `9.2.0-beta.1` the lifecycle is `beta`. Refer to [](/cli/changelog/bundle.md#lifecycle-inference). + +:::{note} +The `products` field determines which changelog files are gathered for consideration. You can still apply [rules](#rules) afterward to further filter changelogs from the bundle. The input stage and bundle filtering stage are conceptually separate. +::: + +## Create bundles + +If you created profiles, you can use them with the `changelog bundle` command like this: ```sh docs-builder changelog bundle ``` -The second argument accepts a version string, a promotion report URL/path, or a URL list file (a plain-text file with one fully-qualified GitHub URL per line). When your profile uses `{version}` in its `output` or `output_products` pattern and you also want to filter by a report, pass both. -For example: +The second argument accepts a version string, a promotion report URL or path, or a URL list file (a plain-text file with one fully-qualified GitHub URL per line). +If you are using a `{version}` placeholder in the `output_products` or `output` fields, you must provide that value as well as your report or URL argument. + +If the source of truth for what was shipped in each release is: + +- a list of GitHub pull requests or issues: + + ```sh + # Bundle changelogs from a PR list ({version} → "2026-02-13") + docs-builder changelog bundle serverless-report 2026-02-13 ./prs.txt + ``` + +- a buildkite promotion report: + + ```sh + # Bundle changelogs from a buildkite report ({lifecycle} → "ga" inferred from "9.2.0") + docs-builder changelog bundle elasticsearch-report 9.2.0 ./promotion-report.html + ``` + +- automated release notes for GitHub releases: + + ```sh + docs-builder changelog bundle agent-gh-release 1.34.1 + + # Use "latest" to fetch the most recent release + docs-builder changelog bundle agent-gh-release latest + ``` + + Alternatively, use the [changelog gh-release](/cli/changelog/gh-release.md) command, which creates the changelogs and bundles at the same time. + +- all changelog files that exist in a specific folder: + + ```sh + docs-builder changelog bundle release-all '*' + ``` + +- all changelog files that match specific products, versions, and lifecycles: + + ```sh + # Bundle changelogs for a GA release ({lifecycle} → "ga" inferred from "9.2.0") + docs-builder changelog bundle elasticsearch-release 9.2.0 + + # Bundle changelogs for a beta release ({lifecycle} → "beta" inferred from "9.2.0-beta.1") + docs-builder changelog bundle elasticsearch-release 9.2.0-beta.1 + + # Bundle changelogs with partial dates + docs-builder changelog bundle serverless-monthly 2026-02 + ``` + +By default all changelogs that match the chosen source of truth are included in the bundle. +To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. + +:::{note} +For profiles that use static patterns (without `{version}` or `{lifecycle}` placeholders), the second argument is still required but serves no functional purpose. You can pass any placeholder value. + +```sh +# Profile with static patterns - second argument unused but required +docs-builder changelog bundle release-all '*' +docs-builder changelog bundle release-all 'unused' +docs-builder changelog bundle release-all 'none' +``` +::: + +If you prefer to specify all the command options every time you run the command refer to [changelog bundle](/cli/changelog/bundle.md#option-based-examples). + +## Amend bundles [changelog-bundle-amend] + +When you need to add changelogs to an existing bundle without modifying the original file, you can use the `docs-builder changelog bundle-amend` command to create amend bundles. +Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number. + +When bundles are loaded (either via the `changelog render` command or the `{changelog}` directive), amend files are **automatically merged** with their parent bundles. +The changelogs from all matching amend files are combined with the parent bundle's changelogs and the result is rendered as a single release. + +:::{warning} +If you explicitly list the amend bundles in the `--input` option of the `docs-builder changelog render` command, you'll get duplicate entries in the output files. List only the original bundles. +::: + +For more details and examples, go to [](/cli/changelog/bundle-amend.md). + +## Remove changelog files [changelog-remove] + +A single changelog file might be applicable to multiple releases (for example, it might be delivered in both Stack and {{serverless-short}} releases or {{ech}} and Enterprise releases on different timelines). +After it has been included in all of the relevant bundles, it is reasonable to delete the changelog to keep your repository clean. + +:::{important} +If you create docs with changelog directives, run the `docs-builder changelog bundle` command with the `--resolve` option or set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained). +Otherwise, the build will fail if you remove changelogs that the directive requires. + +Likewise, the `docs-builder changelog render` command fails for "unresolved" bundles after you delete the changelogs. +::: + +You can use the `docs-builder changelog remove` command to remove changelogs. +It supports the same two modes as `changelog bundle`: you can specify all the command options or you can define "profiles" in the changelog configuration file. +In the command option mode, exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version`, or `--report`. + +Before deleting, the command automatically scans for bundles that still hold unresolved (`file:`) references to the matching changelog files. +If any are found, the command reports an error for each dependency. +This check prevents the `{changelog}` directive from failing at build time with missing file errors. +To proceed with removal even when unresolved bundle dependencies exist, use `--force`. + +To preview what would be removed without deleting anything, use `--dry-run`. +Bundle dependency conflicts are also reported in dry-run mode. + +### Removal with profiles [changelog-remove-profile] + +If your `changelog.yml` configuration file defines `bundle.profiles`, you can use those profiles with `changelog remove`. +This is the easiest way to remove exactly the changelogs that were included in a profile-based bundle. +The command syntax is: ```sh -# Standard profile: lifecycle is inferred from the version string -docs-builder changelog bundle elasticsearch-release 9.2.0 # {lifecycle} → "ga" -docs-builder changelog bundle elasticsearch-release 9.2.0-beta.1 # {lifecycle} → "beta" +docs-builder changelog remove +``` + +For example, if you bundled with: -# Standard profile: filter by a promotion report (version used for {version}) -docs-builder changelog bundle elasticsearch-release ./promotion-report.html -docs-builder changelog bundle elasticsearch-release 9.2.0 ./promotion-report.html +```sh +docs-builder changelog bundle elasticsearch-release 9.2.0 +``` + +You can remove the same changelogs with: + +```sh +docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run ``` - +The `output`, `output_products`, `hide_features`, `link_allow_repos`, and `resolve` fields are bundle-specific and are always ignored for removal (along with other bundle-only settings that do not affect which changelog files match the filter). +Which other fields are used depends on the profile type: + +- Standard profiles: only the `products` field is used. The `repo` and `owner` fields are ignored (they only affect bundle output metadata). +- GitHub release profiles (`source: github_release`): `source`, `repo`, and `owner` are all used. The command fetches the PR list from the GitHub release identified by the version argument and removes changelogs whose `prs` field matches. + +For example, given a GitHub release profile: + +```sh +docs-builder changelog remove agent-gh-release v1.34.0 --dry-run +``` + +This fetches the PR list from the `v1.34.0` release (using the profile's `repo`/`owner` settings) and removes matching changelogs. + +:::{note} +`source: github_release` profiles require a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. +::: + +Profile-based removal is mutually exclusive with command options. +The only options allowed alongside a profile name are `--dry-run` and `--force`. + +You can also pass a promotion report URL, file path, or URL list file as the second argument, and the command removes changelogs whose pull request or issue URLs appear in the report: + +```sh +docs-builder changelog remove elasticsearch-release https://buildkite.../promotion-report.html +docs-builder changelog remove serverless-release 2026-02 ./promotion-report.html +docs-builder changelog remove serverless-release 2026-02 ./prs.txt +``` + +### Removal with command options [changelog-remove-raw] + +You can alternatively remove changelogs based on their issues, pull requests, product metadata, or remove all changelogs from a folder. +Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version` or `--report`. +When using a file for `--prs` or `--issues`, every line must be a fully-qualified GitHub URL. + +```sh +docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run +``` + +For full option details, go to [](/cli/changelog/remove.md). -Top-level `bundle` fields: +## Examples -| Field | Description | -|---|---| -| `repo` | Default GitHub repository name applied to all profiles. Falls back to product ID if not set at any level. | -| `owner` | Default GitHub repository owner applied to all profiles. | -| `resolve` | When `true`, embeds full changelog entry content in the bundle (same as `--resolve`). Required when `link_allow_repos` is set. | -| `link_allow_repos` | When set (including an empty list), only PR/issue links whose resolved repository is in this `owner/repo` list are kept; others are rewritten to `# PRIVATE:` sentinels in bundle YAML. When absent, no link filtering is applied. Requires `resolve: true`. Refer to [PR and issue link allowlist](/cli/changelog/bundle.md#link-allowlist). | +### Apply bundle rules [rules] -Profile configuration fields in `bundle.profiles`: +:::{tip} +Not everything that was shipped in a release and has a changelog necessarily belongs in the release bundle. +::: -| Field | Description | -|---|---| -| `source` | Optional. Set to `github_release` to fetch the PR list from a GitHub release. Mutually exclusive with `products`. Requires `repo` at the profile or `bundle` level. | -| `products` | Product filter pattern with `{version}` and `{lifecycle}` placeholders. Used to match changelog files. Required when filtering by product metadata. Not used when the filter comes from a promotion report, URL list file, or `source: github_release`. | -| `output` | Output file path pattern with `{version}` and `{lifecycle}` placeholders. | -| `output_products` | Optional override for the products array written to the bundle. Useful when the bundle should have a single product ID though it's filtered from many or have a different lifecycle or version than the filter. With multiple product IDs, Mode 3 rule resolution uses the first alphabetically; use separate profiles or bundle runs with a single product in `output_products` when you need a different rule context. | -| `repo` | Optional. Overrides `bundle.repo` for this profile only. Required when `source: github_release` is used and no `bundle.repo` is set. | -| `owner` | Optional. Overrides `bundle.owner` for this profile only. | -| `hide_features` | List of feature IDs to embed in the bundle as hidden. | +If you want to automatically include or exclude changelogs from bundles based on their areas, types, or products, you can accomplish this with rules in your changelog configuration file. +For example, you might choose to omit `other` or `docs` types of changelogs. +Or you might choose to omit all changelogs related to specific features (`areas`) from a specific product's release bundles. -Example profile configuration: +You can define rules at the global level (applies to all products) like this: ```yaml -bundle: - repo: elasticsearch # The default repository for PR and issue links. - owner: elastic # The default repository owner for PR and issue links. - directory: docs/changelog # The directory that contains changelog files. - output_directory: docs/releases # The directory that contains changelog bundles. - # Optional: Default bundle description with placeholder support - description: | - This release includes new features and bug fixes. - - For more information, see the [release notes](https://www.elastic.co/docs/release-notes/elasticsearch#elasticsearch-{version}). - profiles: - elasticsearch-release: - products: "elasticsearch {version} {lifecycle}" - output: "elasticsearch/{version}.yaml" - output_products: "elasticsearch {version}" - # Profile-specific description overrides bundle.description - description: | - Elasticsearch {version} includes: - - Performance improvements - - Bug fixes and stability enhancements - - Download the release binaries: https://github.com/{owner}/{repo}/releases/tag/v{version} - hide_features: - - feature:experimental-api - serverless-release: - products: "cloud-serverless {version} *" - output: "serverless/{version}.yaml" - output_products: "cloud-serverless {version}" - # inherits repo: elasticsearch and owner: elastic from bundle level - # Multi-product profile: rule context for Mode 3 is the first product alphabetically (here: kibana). - # For security-specific rules only, use a separate profile with output_products listing only security. - kibana-security-release: - products: "kibana {version} {lifecycle}, security {version} {lifecycle}" - output: "kibana-security/{version}.yaml" - output_products: "kibana {version}, security {version}" +rules: + bundle: + exclude_products: elasticsearch + exclude_types: deprecation + exclude_areas: + - Internal +``` + +Alternatively, you can define product-specific rules: + +```yaml +rules: + bundle: + products: + cloud-serverless: + include_areas: + - "Search" + - "Monitoring" + elasticsearch: + exclude_areas: + - Autoscaling ``` +Product-specific rules override the global rules entirely—they do not merge. +For details, refer to [](/contribute/configure-changelogs-ref.md#rules-bundle) and [](/contribute/configure-changelogs-ref.md#advanced-rule-examples). + + ### Bundle changelogs from a GitHub release [changelog-bundle-profile-github-release] Set `source: github_release` on a profile to make `changelog bundle` fetch the PR list directly from a published GitHub release. @@ -246,7 +483,35 @@ agent-gh-release-preview: `source: github_release` is mutually exclusive with `products`, and a third positional argument (promotion report or URL list) is not accepted by this profile type. -## Filter by product [changelog-bundle-product] +### Option-based bundling [changelog-bundle-options] + +You can specify only one of the following filter options: + +- `--all`: Include all changelogs from the directory. +- `--input-products`: Include changelogs for the specified products. Refer to [Filter by product](#changelog-bundle-product). +- `--prs`: Include changelogs for the specified pull request URLs, or a path to a newline-delimited file. When using a file, every line must be a fully-qualified GitHub URL such as `https://github.com/owner/repo/pull/123`. Go to [Filter by pull requests](#changelog-bundle-pr). +- `--issues`: Include changelogs for the specified issue URLs, or a path to a newline-delimited file. When using a file, every line must be a fully-qualified GitHub URL such as `https://github.com/owner/repo/issues/123`. Go to [Filter by issues](#changelog-bundle-issues). +- `--release-version`: Bundle changelogs for the pull requests in GitHub release notes. Refer to [Bundle by GitHub release](#changelog-bundle-release-version). +- `--report`: Include changelogs whose pull requests appear in a promotion report. Accepts a URL or a local file path to an HTML report. + +`rules.bundle` in `changelog.yml` is **not** mutually exclusive with these options: it runs as a **second stage** after the primary filter matches entries (for example, `--input-products` gathers changelogs, then global or per-product bundle rules may exclude some). The only mutually exclusive pairing is **profile-based** versus **option-based** invocation. See [bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). + +By default, the output file contains only the changelog file names and checksums. +To change this behavior, set `bundle.resolve` to `true` in the changelog configuration file or use the `--resolve` command option. + +:::{tip} +If you plan to use [changelog directives](/contribute/publish-changelogs.md#changelog-directive), it is recommended to pull all of the content from each changelog into the bundle; otherwise you can't delete your changelogs. +If you likewise want to regenerate your [Asciidoc or Markdown files](/contribute/publish-changelogs.md#render-changelogs) after deleting your changelogs, it's only possible if you have "resolved" bundles. +::: + + + +### Filter by product [changelog-bundle-product] You can use the `--input-products` option to create a bundle of changelogs that match the product details. When using `--input-products`, you must provide all three parts: product, target, and lifecycle. @@ -302,7 +567,7 @@ entries: 1. By default these values match your `--input-products` (even if the changelogs have more products). To specify different product metadata, use the `--output-products` option. -## Filter by pull requests [changelog-bundle-pr] +### Filter by pull requests [changelog-bundle-pr] You can use the `--prs` option to create a bundle of the changelogs that relate to those pull requests. You can provide either a comma-separated list of PRs (`--prs "https://github.com/owner/repo/pull/123,12345"`) or a path to a newline-delimited file (`--prs /path/to/file.txt`). @@ -343,7 +608,7 @@ entries: checksum: 451d60283fe5df426f023e824339f82c2900311e ``` -## Filter by issues [changelog-bundle-issues] +### Filter by issues [changelog-bundle-issues] You can use the `--issues` option to create a bundle of changelogs that relate to those GitHub issues. Provide either a comma-separated list of issues (`--issues "https://github.com/owner/repo/issues/123,456"`) or a path to a newline-delimited file (`--issues /path/to/file.txt`). @@ -356,7 +621,7 @@ docs-builder changelog bundle --issues "12345,12346" \ --output-products "elasticsearch 9.2.2 ga" ``` -## Filter by pull request or issue file [changelog-bundle-file] +### Filter by pull request or issue file [changelog-bundle-file] If you have a file that lists pull requests (such as PRs associated with a GitHub release), you can pass it to `--prs`. For example, if you have a file that contains full pull request URLs like this: @@ -414,7 +679,7 @@ entries: When a changelog matches multiple `--input-products` filters, it appears only once in the bundle. This deduplication applies even when using `--all` or `--prs`. ::: -## Filter by GitHub release notes [changelog-bundle-release-version] +### Filter by GitHub release notes [changelog-bundle-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), you can use the `--release-version` option to derive the PR list from those release notes. For example: @@ -439,7 +704,7 @@ If you are not creating changelogs when you create your pull requests, consider It 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) ::: -## Hide features [changelog-bundle-hide-features] +### Hide features [changelog-bundle-hide-features] You can use the `--hide-features` option to embed feature IDs that should be hidden when the bundle is rendered. This is useful for features that are not yet ready for public documentation. @@ -479,7 +744,7 @@ When this bundle is rendered (either via the `changelog render` command or the ` The `--hide-features` option on the `render` command and the `hide-features` field in bundles are **combined**. If you specify `--hide-features` on both the `bundle` and `render` commands, all specified features are hidden. The `{changelog}` directive automatically reads `hide-features` from all loaded bundles and applies them. ::: -## Hide private links +### Hide private links A changelog can reference multiple pull requests and issues in the `prs` and `issues` array fields. @@ -490,108 +755,3 @@ If you are working in a private repo and do not want any pull request or issue l :::{tip} You must run the `docs-builder changelog bundle` command with the `--resolve` option or set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained) in order to hide the private links. ::: - -## Amend bundles [changelog-bundle-amend] - -When you need to add changelogs to an existing bundle without modifying the original file, you can use the `docs-builder changelog bundle-amend` command to create amend bundles. -Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number. - -When bundles are loaded (either via the `changelog render` command or the `{changelog}` directive), amend files are **automatically merged** with their parent bundles. -The changelogs from all matching amend files are combined with the parent bundle's changelogs and the result is rendered as a single release. - -:::{warning} -If you explicitly list the amend bundles in the `--input` option of the `docs-builder changelog render` command, you'll get duplicate entries in the output files. List only the original bundles. -::: - -For more details and examples, go to [](/cli/changelog/bundle-amend.md). - -## Remove changelog files [changelog-remove] - -A single changelog file might be applicable to multiple releases (for example, it might be delivered in both Stack and {{serverless-short}} releases or {{ech}} and Enterprise releases on different timelines). -After it has been included in all of the relevant bundles, it is reasonable to delete the changelog to keep your repository clean. - -:::{important} -If you create docs with changelog directives, run the `docs-builder changelog bundle` command with the `--resolve` option or set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained). -Otherwise, the build will fail if you remove changelogs that the directive requires. - -Likewise, the `docs-builder changelog render` command fails for "unresolved" bundles after you delete the changelogs. -::: - -You can use the `docs-builder changelog remove` command to remove changelogs. -It supports the same two modes as `changelog bundle`: you can specify all the command options or you can define "profiles" in the changelog configuration file. -In the command option mode, exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version`, or `--report`. - -Before deleting, the command automatically scans for bundles that still hold unresolved (`file:`) references to the matching changelog files. -If any are found, the command reports an error for each dependency. -This check prevents the `{changelog}` directive from failing at build time with missing file errors. -To proceed with removal even when unresolved bundle dependencies exist, use `--force`. - -To preview what would be removed without deleting anything, use `--dry-run`. -Bundle dependency conflicts are also reported in dry-run mode. - -### Removal with profiles [changelog-remove-profile] - -If your `changelog.yml` configuration file defines `bundle.profiles`, you can use those profiles with `changelog remove`. -This is the easiest way to remove exactly the changelogs that were included in a profile-based bundle. -The command syntax is: - -```sh -docs-builder changelog remove -``` - -For example, if you bundled with: - -```sh -docs-builder changelog bundle elasticsearch-release 9.2.0 -``` - -You can remove the same changelogs with: - -```sh -docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run -``` - -The command automatically discovers `changelog.yml` by checking `./changelog.yml` then `./docs/changelog.yml` relative to your current directory. -If no configuration file is found, the command returns an error with advice to create one or to run from the directory where the file exists. - -The `output`, `output_products`, `hide_features`, `link_allow_repos`, and `resolve` fields are bundle-specific and are always ignored for removal (along with other bundle-only settings that do not affect which changelog files match the filter). -Which other fields are used depends on the profile type: - -- Standard profiles: only the `products` field is used. The `repo` and `owner` fields are ignored (they only affect bundle output metadata). -- GitHub release profiles (`source: github_release`): `source`, `repo`, and `owner` are all used. The command fetches the PR list from the GitHub release identified by the version argument and removes changelogs whose `prs` field matches. - -For example, given a GitHub release profile: - -```sh -docs-builder changelog remove agent-gh-release v1.34.0 --dry-run -``` - -This fetches the PR list from the `v1.34.0` release (using the profile's `repo`/`owner` settings) and removes matching changelogs. - -:::{note} -`source: github_release` profiles require a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. -::: - -Profile-based removal is mutually exclusive with command options. -The only options allowed alongside a profile name are `--dry-run` and `--force`. - -You can also pass a promotion report URL, file path, or URL list file as the second argument, and the command removes changelogs whose pull request or issue URLs appear in the report: - -```sh -docs-builder changelog remove elasticsearch-release https://buildkite.../promotion-report.html -docs-builder changelog remove serverless-release 2026-02 ./promotion-report.html -docs-builder changelog remove serverless-release 2026-02 ./prs.txt -``` - -### Removal with command options [changelog-remove-raw] - -You can alternatively remove changelogs based on their issues, pull requests, product metadata, or remove all changelogs from a folder. -Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version` or `--report`. -When using a file for `--prs` or `--issues`, every line must be a fully-qualified GitHub URL. - -```sh -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 b1d768d46..9ca561652 100644 --- a/docs/contribute/configure-changelogs-ref.md +++ b/docs/contribute/configure-changelogs-ref.md @@ -38,18 +38,16 @@ These settings are relevant to one or all of the `changelog bundle`, `changelog :::{table} :widths: description - -| Setting | Description | -| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `bundle.description` | Default template for bundle descriptions. Supports `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` placeholders. | -| `bundle.directory` | Input directory containing changelog YAML files (default: `docs/changelog`). | +| Setting | Description | +| ------------------------- | ----------- | +| `bundle.description` | Default template for bundle descriptions. Supports `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` placeholders. | +| `bundle.directory` | Input directory containing changelog YAML files (default: `docs/changelog`). | | `bundle.link_allow_repos` | List of `owner/repo` pairs whose PR/issue links are preserved. When set (including empty `[]`), links to unlisted repos become `# PRIVATE:` sentinels. Requires `bundle.resolve: true` | -| `bundle.output_directory` | Output directory for bundled files (default: `docs/releases`). | -| `bundle.owner` | Default GitHub repository owner (for example, `elastic`). | -| `bundle.release_dates` | When `true`, bundles include a `release-date` field (default: true). | -| `bundle.repo` | Default GitHub repository name (for example, `elasticsearch`). | -| `bundle.resolve` | When `true`, changelog contents are copied into bundle (default: `true`). | - +| `bundle.output_directory` | Output directory for bundled files (default: `docs/releases`). | +| `bundle.owner` | Default GitHub repository owner (for example, `elastic`). | +| `bundle.release_dates` | When `true`, bundles include a `release-date` field (default: true). | +| `bundle.repo` | Default GitHub repository name (for example, `elasticsearch`). Used by the `{changelog}` directive to generate correct PR and issue links. Only needed when the product ID doesn't match the GitHub repository name. | +| `bundle.resolve` | When `true`, changelog contents are copied into bundle (default: `true`). | ::: @@ -62,29 +60,59 @@ When `bundle.link_allow_repos` is omitted, no link filtering occurs. ### Bundle profiles [bundle-profiles] -Named profiles simplify bundle creation for different release scenarios. -Profiles work with both `changelog bundle` and `changelog remove` commands. - -These settings are located in the `bundle.profiles.` section of the configuration file. - -:::{table} -:widths: description - - -| Profile setting | Description | -| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| `description` | Profile-specific description template. Overrides `bundle.description`. | -| `hide_features` | List of feature IDs to mark as hidden (commented out) in bundle output. | -| `output` | Output filename pattern (for example, `"elasticsearch/{version}.yaml"`). | -| `output_products` | Products list in bundle metadata; supports placeholders. | -| `owner` | Profile-specific GitHub owner. Overrides `bundle.owner`. | -| `products` | Product filter pattern (for example, `"elasticsearch {version} {lifecycle}"`) where placeholders are substituted at runtime. | -| `release_dates` | When `true`, bundles include a `release-date` field. Overrides `bundle.release_dates`. | -| `repo` | Profile-specific GitHub repository name. Overrides `bundle.repo`. | -| `source` | When set to `"github_release"`, fetches PR list from GitHub release instead of filtering changelogs. Mutually exclusive with `products`. | - - -::: +Named profiles enable you to run commands repeatedly with consistent options. +They work with both `changelog bundle` and `changelog remove` commands. + +These settings are located in the `bundle.profiles.` section of the configuration file: + +`description` +: Overrides the global [bundle.description](#bundle-basic). + +`hide_features` +: Feature IDs to mark as hidden in the bundle. +: When the bundle is rendered, entries with matching `feature-id` values are commented out. + +`output` +: The output filename pattern for the bundle file. +: Supports `{version}` and `{lifecycle}` placeholders. +: When not set, the output path falls back in order to: `bundle.output_directory/changelog-bundle.yaml` (if `bundle.output_directory` is configured), then `changelog-bundle.yaml` in the input directory. +: Setting this is recommended so each profile produces a distinctly named file rather than overwriting the default. +: Example: `"elasticsearch/{version}.yaml"` + +`output_products` +: The bundle's `products` metadata, which affects the bundle rules that are applied and the product and version titles that ultimately appear in documentation. +: Supports `{version}` and `{lifecycle}` placeholders. +: When not set, the products array is derived from the individual changelog files matched by the filter. This often produces multiple product entries (one per unique product/target/lifecycle combination across all matched files), which may not reflect a single clean release identity. +: When set, the products array in the bundle is exactly the value you specify, replacing anything that would be derived from the matched changelogs. Use this to publish a single, authoritative product entry with a specific version and lifecycle. +: 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 [](/cli/changelog/bundle.md#lifecycle-inference). +: 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 [](/cli/changelog/bundle.md#product-format). + +`owner` +: Overrides [bundle.owner](#bundle-basic). + +`products` +: Derive the list of changelogs by matching their `products` values (equivalent to the `--input-products` command option). +: Not used when the source of truth for the release is a promotion report, URL list file, or `source: github_release`; in those cases this setting is ignored. +: Supports `{version}` and `{lifecycle}` placeholders that are substituted at runtime. +: The value `"* * *"` is equivalent to the `--all` command option. +: Example: `"elasticsearch {version} {lifecycle}"` +: Refer to [](/cli/changelog/bundle.md#product-format). + +`release_dates` +: Overrides [bundle.release_dates](#bundle-basic). + +`repo` +: Overrides [bundle.repo](#bundle-basic). +: Required when `source: github_release` is used and `bundle.repo` is not set. + +`source` +: Derive the list of changelogs from the specified source. +: Only `github_release` is currently supported (equivalent to the `--release-version` command option), which means a PR list is fetched from the GitHub release identified by the version argument. +: Requires `repo` to be set at the profile or `bundle` level. +: Mutually exclusive with `products`. +: Example: `source: github_release` Example profile usage: @@ -286,10 +314,16 @@ rules: exclude: ">non-issue, ILM" ``` +For more context, go to [](/contribute/create-changelogs.md#rules). + ### `rules.bundle` [rules-bundle] Controls which changelogs are included in bundles. -These rules are applied by the `docs-builder changelog bundle` and `docs-builder changelog gh-release` commands **after** the primary filter (`--prs`, `--issues`, `--all`, or `--input-products`) has identified the relevant changelogs. +These rules are applied by the `docs-builder changelog bundle` and `docs-builder changelog gh-release` commands **after** the primary filter (`--prs`, `--issues`, `--all`, or `--input-products`) has identified the relevant changelogs and **before** the bundle is written. + +:::{tip} +The input stage (gathering entries) and bundle filtering stage (filtering for output) are conceptually separate. +::: These settings are located in the `rules.bundle` section of the configuration file: @@ -298,9 +332,9 @@ These settings are located in the `rules.bundle` section of the configuration fi | `exclude_areas` | string or list | Changelog areas to exclude from the bundle. | | `exclude_products` | string or list | Changelog products to exclude from the bundle. | | `exclude_types` | string or list | Changelog types to exclude from the bundle. | -| `include_areas` | string or list | Only changelogs with these areas are included. | -| `include_products` | string or list | Only changelogs with these product IDs are included. | -| `include_types` | string or list | Only changelogs with these types are included. | +| `include_areas` | string or list | Changelog areas to include in the bundle. | +| `include_products` | string or list | Changelog products to include in the bundle. | +| `include_types` | string or list | Changelog types to include in the bundle. | | `match_areas` | string | Override `rules.match` for area matching. Values: `any`, `all`, `conjunction`. | | `match_products` | string | Override `rules.match` for product matching. Values: `any`, `all`, `conjunction`. | | `products` | map | Per-product type/area filter overrides. Refer to [](#rules-bundle-products).| diff --git a/docs/contribute/configure-changelogs.md b/docs/contribute/configure-changelogs.md index 7dfc230b2..244cef86c 100644 --- a/docs/contribute/configure-changelogs.md +++ b/docs/contribute/configure-changelogs.md @@ -64,7 +64,23 @@ For example, run the following command in your GitHub repo's root directory: docs-builder changelog init ``` -By default, it creates `docs/changelog.yml` file that contains settings like this: +## Review the settings + +1. Find the configuration file. + By default, the `changelog init` command creates `docs/changelog.yml`. + If you move or rename this file, there will be extra steps when you configure its [usage](#usage). +1. Review the settings and update them based on your preferences. + For descriptions of all the settings, refer to [](/contribute/configure-changelogs-ref.md). + For example: + - To limit the acceptable values, update [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) and [products](/contribute/configure-changelogs-ref.md#products). + - To set the changelog file name pattern, update [filename](/contribute/configure-changelogs-ref.md#filename). + - To control what is extracted from GitHub, update [extract](/contribute/configure-changelogs-ref.md#extract). + - To change bundle default behaviour or create reusable profiles, update [bundle](/contribute/configure-changelogs-ref.md#bundle). + - If you have GitHub labels to set changelog areas, types, or products, update [pivot](/contribute/configure-changelogs-ref.md#pivot). + - If you have GitHub labels to opt in or out of changelogs, update [rules.create](/contribute/configure-changelogs-ref.md#rules-create). + - If you want to filter changelogs in or out of release bundles based on their area, type, or products, update [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle). + +For example, a simple `docs/changelog.yml` looks like this: ```yml filename: timestamp @@ -88,27 +104,12 @@ pivot: For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml). -For descriptions of all the settings, refer to [Changelog configuration reference](/contribute/configure-changelogs-ref.md) - -## Rules for creation and bundling [rules] - -If you have pull request labels that indicate a changelog is not required (such as `>non-issue` or `release_note:skip`), you can declare these in the `rules.create` section of the changelog configuration. - -When you run the `docs-builder changelog add` command with the `--prs` or `--issues` options and the pull request or issue has one of the identified labels, the command does not create a changelog. - -Likewise, if you want to exclude changelogs with certain products, areas, or types from the release bundles, you can declare these in the `rules.bundle` section of the changelog configuration. -For example, you might choose to omit `other` or `docs` changelogs. -Or you might want to omit all autoscaling-related changelogs from the Cloud Serverless release bundles. - -You can define rules at the global level (applies to all products) or for specific products. -Product-specific rules override the global rules entirely—they do not merge. -For details, refer to [Rules](/contribute/configure-changelogs-ref.md#rules). - -## Use a changelog configuration file +## Use a changelog configuration file [usage] After you've created a config file, all subsequent changelog commands can use it. -By default, they look for `docs/changelog.yml` but you can specify a different path with the `--config` command option. +By default, they look for `changelog.yml` by checking `./changelog.yml` then `./docs/changelog.yml` relative to your current directory. +Most changelog commands allow you to specify a different path with the `--config` option. For specific details about the usage and impact of the configuration file, refer to the [changelog commands](/cli/changelog/index.md). -The [changelog directive](/syntax/changelog.md) also uses the changelog configuration file and you can specify a non-default path if necessary. +The [changelog directive](/syntax/changelog.md) also uses the changelog configuration file and you can specify a non-default path if necessary. \ No newline at end of file diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index 34251447b..282171521 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -52,6 +52,8 @@ If you already have automated release notes for GitHub releases, you can use the ## Create changelogs from GitHub actions [github-actions] +For details about this method, refer to the [README](https://github.com/elastic/docs-actions/blob/main/changelog/README.md). + 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`. @@ -93,10 +95,10 @@ You can further limit the possible values with the [products](/contribute/config ## Examples -### Control changelog creation [example-block-label] +### Control changelog creation [rules] -You can prevent changelog creation for PRs based on their labels. -For example, your configuration file can contain a `rules.create` section like this: +If you want to automatically block the creation of changelogs for pull requests or issues based on their labels, you can accomplish this with rules in your changelog configuration file. +For example, your `changelog.yml` file can contain a `rules.create` section like this: ```yaml rules: @@ -110,7 +112,11 @@ rules: exclude: ">non-issue, >test" ``` -Those settings affect commands with the `--prs` or `--issues` options, for example: +You can define rules at the global level (applies to all products) or for specific products (`cloud-serverless` in this example). +Product-specific rules override the global rules entirely—they do not merge. + +When you run the `docs-builder changelog add` command with the `--prs` or `--issues` options and the pull request or issue has one of the identified labels, the command does not create a changelog. +For example: ```sh docs-builder changelog add --prs "1234, 5678" \ @@ -120,8 +126,7 @@ docs-builder changelog add --prs "1234, 5678" \ 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. -Alternatively, you can define `rules.create.include` labels. -For example, to only create changelogs for PRs with specific labels: +Alternatively, you can define `rules.create.include` to only create changelogs for PRs with specific labels: ```yaml rules: diff --git a/docs/syntax/changelog.md b/docs/syntax/changelog.md index 3d1ef5997..3f26386c5 100644 --- a/docs/syntax/changelog.md +++ b/docs/syntax/changelog.md @@ -133,10 +133,9 @@ Both explicit and auto-discovered paths must resolve within the repository check You can filter changelog entries at bundle time using the `rules.bundle` configuration in your `changelog.yml` file. This is evaluated during `changelog bundle` and `changelog gh-release`, before the bundle is written. Entries that don't match are excluded from the bundle entirely. -The `{changelog}` directive and the `changelog render` command both do not apply `rules.publish`. To filter entries, use `rules.bundle` at bundle time so entries are excluded before bundling. Both receive only the bundled entries. See the [changelog bundle documentation](/cli/changelog/bundle.md#changelog-bundle-rules) for full syntax. - +The `{changelog}` directive and the `changelog render` command both do not apply `rules.publish`. To filter entries, use `rules.bundle` at bundle time so entries are excluded before bundling. Both receive only the bundled entries. `rules.bundle` supports product, type, and area filtering, and per-product overrides. -For full syntax, refer to the [rules for filtered bundles](/cli/changelog/bundle.md#changelog-bundle-rules). +For full syntax, refer to the [](/contribute/configure-changelogs-ref.md#rules-bundle). ## Hiding features From 1b80d73ae16d63c7cfed2d5634b5fe17976c753b Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 30 Apr 2026 08:52:03 -0700 Subject: [PATCH 2/6] Fix code callouts --- docs/contribute/bundle-changelogs.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/contribute/bundle-changelogs.md b/docs/contribute/bundle-changelogs.md index 26e66cac7..060c46550 100644 --- a/docs/contribute/bundle-changelogs.md +++ b/docs/contribute/bundle-changelogs.md @@ -66,22 +66,24 @@ For example: ```yaml bundle: - directory: docs/changelog # The directory that contains changelog files. - output_directory: docs/releases # The directory that contains changelog bundles. - repo: elasticsearch # The default repository for PR and issue links. - owner: elastic # The default repository owner for PR and issue links. - profiles: + directory: docs/changelog <1> + output_directory: docs/releases <2> + repo: elasticsearch + owner: elastic + profiles: # Find changelogs that match a list of PRs serverless-report: - output: "serverless-{version}.yaml" <1> - output_products: "cloud-serverless {version}" <2> + output: "serverless-{version}.yaml" <3> + output_products: "cloud-serverless {version}" <4> elasticsearch-report: output: "elasticsearch-{version}.yaml" output_products: "elasticsearch {version} {lifecycle}" ``` -<1> If the `output` and `output_products` are omitted, the default path and file names are used. This example shows how you can use a `{version}` variable to customize the bundle's filename. -<2> You can likewise set the bundle's product metadata, which affects the rules that are applied and the product and version titles that ultimately appear in the documentation. +1. The directory that contains changelog files. +2. The directory that contains changelog bundles. +3. If the `output` and `output_products` are omitted, the default path and file names are used. This example shows how you can use a `{version}` variable to customize the bundle's filename. +4. You can likewise set the bundle's product metadata, which affects the rules that are applied and the product and version titles that ultimately appear in the documentation. ### Bundle by GitHub releases [profile-gh-release] From e13ae4eec925598953158c44db44abe80ebaf54a Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 5 May 2026 10:48:20 -0700 Subject: [PATCH 3/6] Clean up examples --- docs/cli/changelog/bundle.md | 185 +++++++++-- docs/cli/changelog/remove.md | 105 +------ docs/contribute/bundle-changelogs.md | 441 +++++---------------------- 3 files changed, 249 insertions(+), 482 deletions(-) diff --git a/docs/cli/changelog/bundle.md b/docs/cli/changelog/bundle.md index 8f1c0452a..809ac8ba2 100644 --- a/docs/cli/changelog/bundle.md +++ b/docs/cli/changelog/bundle.md @@ -292,21 +292,6 @@ Sentinel values are omitted from rendered documentation but remain in bundle fil ## Option-based examples -### Bundle by report or URL list - -You can use `--report` to filter by a promotion report: - -```sh -# Extract PRs from a downloaded report and use them as the filter -docs-builder changelog bundle \ - --report ./promotion-report.html \ - --directory ./docs/changelog \ - --output ./docs/releases/bundle.yaml -``` - -By default all changelogs that match PRs in the promotion report are included in the bundle. -To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. - ### Bundle by GitHub release [changelog-bundle-release-version] You can use `--release-version` to fetch pull request references directly from GitHub release notes and use them as the bundle filter. @@ -321,29 +306,171 @@ docs-builder changelog bundle \ --release-version v1.34.0 \ --repo apm-agent-dotnet \ <1> --owner elastic <2> + --output-products "apm-agent-dotnet 1.34.0 ga" <3> ``` 1. You must specify `--repo` or set `bundle.repo` in the changelog configuration file. 2. If you don't specify `--owner`, it uses `bundle.owner` in the changelog configuration or else defaults to `elastic`. +3. The bundle's product metadata is inferred automatically from the release tag and repository name; you can override that behavior with the `--output-products` option. + +:::{note} +`--release-version` requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. +::: + +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](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. + +:::{tip} +If you are not creating changelogs when you create your pull requests, consider the `docs-builder changelog gh-release` command as a one-shot alternative to the `changelog add` and `changelog bundle` commands. +It 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) +::: + +### Bundle by issues [changelog-bundle-issues] -Without `--output-products`, the products array in the bundle is derived from the matched changelog files' own `products` fields — the same behavior as `--prs`, `--issues`, `--report`, and `--all`. -Use `--output-products` when you need a single, authoritative product entry that reflects the release identity rather than the diverse metadata across individual changelog files. +You can use the `--issues` option to create a bundle of changelogs that relate to those GitHub issues. +Issues can be identified by a full URL (such as `https://github.com/owner/repo/issues/123`), a short format (such as `owner/repo#123`), or just a number (in which case `--owner` and `--repo` are required — or set via `bundle.owner` and `bundle.repo` in the configuration). + +```sh +docs-builder changelog bundle --issues "12345,12346" \ + --repo elasticsearch \ + --owner elastic \ + --output-products "elasticsearch 9.2.2 ga" +``` + +Alternatively, you can specify a path to a newline-delimited file that contains the issue URLS (for example, `--issues /path/to/file.txt`). +In this case, you cannot use short URLs or numbers, each line must have a full URL. + +By default all changelogs that match issues in the list are included in the bundle. +To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. + + +### Bundle by pull requests [changelog-bundle-pr] + +You can use the `--prs` option to create a bundle of the changelogs that relate to those pull requests. + +Pull requests can be identified by a full URL (such as `https://github.com/owner/repo/pull/123`), a short format (such as `owner/repo#123`), or just a number. + +```sh +docs-builder changelog bundle --prs "108875,135873,136886" \ <1> + --repo elasticsearch \ <2> + --owner elastic \ <3> + --output-products "elasticsearch 9.2.2 ga" <4> +``` + +1. The comma-separated list of pull request numbers to seek. +2. The repository in the pull request URLs. Not required when using full PR URLs, or when `bundle.repo` is set in the changelog configuration. +3. The owner in the pull request URLs. Not required when using full PR URLs, or when `bundle.owner` is set in the changelog configuration. +4. The product metadata for the bundle. If it is not provided, it will be derived from all the changelog product values. + +Alternatively, you can specify a path to a newline-delimited file that contains the PR URLS (for example, `--prs /path/to/file.txt`). +In this case, you cannot use short URLs or numbers, each line must have a full URL. For example: +```txt +https://github.com/elastic/elasticsearch/pull/108875 +https://github.com/elastic/elasticsearch/pull/135873 +https://github.com/elastic/elasticsearch/pull/136886 +https://github.com/elastic/elasticsearch/pull/137126 +``` + +By default all changelogs that match PRs in the list are included in the bundle. +To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. + +If you have changelog files that reference those pull requests, the command creates a file like this: + +```yaml +products: +- product: elasticsearch + target: 9.2.2 + lifecycle: ga +entries: +- file: + name: 1765507819-fix-ml-calendar-event-update-scalability-issues.yaml + checksum: 069b59edb14594e0bc3b70365e81626bde730ab7 +- file: + name: 1765507798-convert-bytestransportresponse-when-proxying-respo.yaml + checksum: c6dbd4730bf34dbbc877c16c042e6578dd108b62 +- file: + name: 1765507839-use-ivf_pq-for-gpu-index-build-for-large-datasets.yaml + checksum: 451d60283fe5df426f023e824339f82c2900311e +``` + +### Bundle by product [changelog-bundle-product] + +You can use the `--input-products` option to create a bundle of changelogs that match the product details. +When using `--input-products`, you must provide all three parts: product, target, and lifecycle. +Each part can be a wildcard (`*`) to match any value. + +:::{tip} +If you use profile-based bundling, provide this information in the `bundle.profiles..products` field. +::: + ```sh docs-builder changelog bundle \ - --release-version v1.34.0 \ - --output-products "apm-agent-dotnet 1.34.0 ga" + --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](/cli/changelog/bundle.md#product-format). + +You can use wildcards in any of the three parts: + +```sh +# Bundle any changelogs that have exact matches for either of these clauses +docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 ga, elasticsearch 9.3.0 beta" + +# Bundle all elasticsearch changelogs regardless of target or lifecycle +docs-builder changelog bundle --input-products "elasticsearch * *" + +# Bundle all cloud-serverless 2025-12-02 changelogs with any lifecycle +docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 *" + +# Bundle any cloud-serverless changelogs with target starting with "2025-11-" and "ga" lifecycle +docs-builder changelog bundle --input-products "cloud-serverless 2025-11-* ga" + +# Bundle all changelogs (equivalent to --all) +docs-builder changelog bundle --input-products "* * *" +``` + +If you have changelog files that reference those product details, the command creates a file like this: + +```yaml +products: <1> +- product: cloud-serverless + target: 2025-12-02 +- product: cloud-serverless + target: 2025-12-06 +entries: +- file: + name: 1765495972-fixes-enrich-and-lookup-join-resolution-based-on-m.yaml + checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464 +- file: + name: 1765507778-break-on-fielddata-when-building-global-ordinals.yaml + checksum: 70d197d96752c05b6595edffe6fe3ba3d055c845 ``` +1. By default these values match your `--input-products` (even if the changelogs have more products). +To specify different product metadata, use the `--output-products` option. + :::{note} -`--release-version` requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. +When a changelog matches multiple `--input-products` filters, it appears only once in the bundle. This deduplication applies even when using `--all` or `--prs`. ::: -By default all changelogs that match PRs in the GitHub release notes are included in the bundle. +### Bundle by report + +You can use `--report` to filter by a promotion report: + +```sh +# Extract PRs from a downloaded report and use them as the filter +docs-builder changelog bundle \ + --report ./promotion-report.html \ + --directory ./docs/changelog \ + --output ./docs/releases/bundle.yaml +``` + +By default all changelogs that match PRs in the promotion report are included in the bundle. To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. -### Bundle with description +### Bundle descriptions You can add a description to bundles using the `--description` option. For simple descriptions, use regular quotes: @@ -370,7 +497,7 @@ docs-builder changelog bundle \ --description "Elasticsearch {version} includes performance improvements. Download: https://github.com/{owner}/{repo}/releases/tag/v{version}" ``` -### Bundle with release date +### Bundle release dates You can add a `release-date` field directly to a bundle YAML file. This field is optional and purely informative for end-users. It is especially useful for components released outside the usual stack lifecycle, such as APM agents and EDOT agents. @@ -458,6 +585,7 @@ bundle: output_products: "elasticsearch {version}" # Enables placeholder substitution description: "Download: https://github.com/{owner}/{repo}/releases/tag/v{version}" ``` + ::: #### GitHub release profiles @@ -467,13 +595,12 @@ This means the pre-release suffix on the tag drives the lifecycle value: | Release tag | `{version}` | `{lifecycle}` | |-------------|-------------|---------------| -| `v9.2.0` | `9.2.0` | `ga` | -| `v9.2.0-beta.1` | `9.2.0` | `beta` | -| `v9.2.0-preview.1` | `9.2.0` | `preview` | -| `v1.34.1` | `1.34.1` | `ga` | -| `v1.34.1-preview.1` | `1.34.1` | `preview` | +| `v1.2.3` | `1.2.3` | `ga` | +| `v1.2.3-beta.1` | `1.2.3` | `beta` | +| `v1.2.3-preview.1` | `1.2.3` | `preview` | -This differs from standard profiles, where lifecycle is inferred from the version argument you type. For `source: github_release`, the `{version}` placeholder always uses the clean base version (stripped of any pre-release suffix), while `{lifecycle}` reflects the actual tag format. +This differs from standard profiles, where lifecycle is inferred from the version argument you type. +For `source: github_release`, the `{version}` placeholder always uses the clean base version (stripped of any pre-release suffix), while `{lifecycle}` reflects the actual tag format. If the lifecycle you want to advertise cannot be inferred from the tag format — for example, because your team uses clean tags like `v1.34.1` even for pre-releases — hardcode the lifecycle directly in `output_products` instead of using the `{lifecycle}` placeholder: diff --git a/docs/cli/changelog/remove.md b/docs/cli/changelog/remove.md index bdcfcbe37..cc931dc82 100644 --- a/docs/cli/changelog/remove.md +++ b/docs/cli/changelog/remove.md @@ -142,6 +142,16 @@ Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is r ## Option-based examples +You can remove changelogs based on their issues, pull requests, product metadata, or remove all changelogs from a folder. +Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version` or `--report`. +When using a file for `--prs` or `--issues`, every line must be a fully-qualified GitHub URL. + +For example: + +```sh +docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run +``` + ### Remove by GitHub release [changelog-remove-release-version] You can use `--release-version` to fetch pull request references directly from GitHub release notes and use them as the removal filter. @@ -190,97 +200,4 @@ When a `changelog.yml` configuration file defines `bundle.profiles`, you can use Profile-based commands discover the changelog configuration automatically (no `--config` flag): they look for `changelog.yml` in the current directory, then `docs/changelog.yml`. If neither file is found, the command returns an error with instructions to run `docs-builder changelog init` or to re-run from the folder where the file exists. -### Profile fields - -The `changelog remove` command reads the same `bundle.profiles` configuration as `changelog bundle`, but only a subset of fields are relevant to removal: - -| Field | Used by `changelog remove`? | Notes | -|---|---|---| -| `products` | Yes, when filtering by product | Required when the profile argument is a version string and no `source: github_release` is set. Not needed when the filter comes from a promotion report, URL list file, or `source: github_release`. | -| `source` | Yes | `source: github_release` fetches the PR list from the GitHub release to use as the removal filter. | -| `repo` | Yes, with `source: github_release` | Identifies the GitHub repository to fetch the release from. | -| `owner` | Yes, with `source: github_release` | Identifies the GitHub repository owner. | -| `output` | No | Ignored — removal does not write any output files. | -| `output_products` | No | Ignored. | -| `hide_features` | No | Ignored. | -| `rules.bundle` | No | Ignored — bundle-time product filtering is not applied during removal. | - -### Remove by product - -You can create profiles that are equivalent to the `--products` filter option, that is to say the removal will affect only changelogs with matching `products`. - -```yaml -bundle: - profiles: - elasticsearch-release: - products: "elasticsearch {version} {lifecycle}" - output: "elasticsearch-{version}.yaml" -``` - -You can remove the matching changelogs with: - -```sh -docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run -``` - -This removes changelogs for `elasticsearch 9.2.0 ga` — the same set that `docs-builder changelog bundle elasticsearch-release 9.2.0` would include. The lifecycle is inferred from the version string: `9.2.0` → `ga`, `9.2.0-beta.1` → `beta`. Refer to [](/cli/changelog/bundle.md#lifecycle-inference) for details. - -### Remove by report or URL list - -You can also create profiles that are equivalent to the `--prs`, `--issues`, or `--report` filter options. -That is to say the removal will affect only changelogs with matching `prs` or `issues`. - -For these profile-based commands, you can pass a promotion report URL, a local `.html` file, or a URL list file as the second argument. The command removes changelogs whose `prs` field matches the PR URLs extracted from the report or file. The following commands perform the same task with and without a profile: - -```sh -docs-builder changelog remove serverless-report ./promotion-report.html - -docs-builder changelog remove \ - --report ./promotion-report.html -``` - -Alternatively, use a newline-delimited text file that lists pull request or issue URLs: - -```sh -docs-builder changelog remove serverless-report ./prs.txt -``` - -When you want to use both a version (for `{version}` substitution in the output filename) and a report as the filter, pass both as separate arguments: - -```sh -docs-builder changelog remove serverless-report 2026-02-13 ./promotion-report.html -``` - -### Remove by GitHub release profiles [changelog-remove-github-release-profile] - -To make removal by GitHub release more easily repeatable, create a profile with `source: github_release` in your changelog configuration file. -For example: - -```yaml -bundle: - profiles: - agent-gh-release: - source: github_release - repo: apm-agent-dotnet - owner: elastic - output: "agent-{version}.yaml" -``` - -You can remove the matching changelogs with: - -```sh -docs-builder changelog remove agent-gh-release 1.34.0 -``` - -Use `--dry-run` to preview the files that would be deleted before committing: - -```sh -docs-builder changelog remove agent-gh-release 1.34.0 --dry-run -``` - -:::{note} -`source: github_release` profiles require a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. -The `repo` and `owner` used to identify the release follow the same precedence as bundling: profile-level `repo`/`owner` override `bundle.repo`/`bundle.owner`, which in turn override the default owner `elastic`. -::: - -For the full list of profile configuration fields, go to [](/contribute/configure-changelogs-ref.md#bundle-profiles). +Refer to [](/contribute/bundle-changelogs.md#changelog-remove) for examples. diff --git a/docs/contribute/bundle-changelogs.md b/docs/contribute/bundle-changelogs.md index 060c46550..a5a34a865 100644 --- a/docs/contribute/bundle-changelogs.md +++ b/docs/contribute/bundle-changelogs.md @@ -70,20 +70,21 @@ bundle: output_directory: docs/releases <2> repo: elasticsearch owner: elastic - profiles: - # Find changelogs that match a list of PRs + resolve: true <3> + profiles: serverless-report: - output: "serverless-{version}.yaml" <3> - output_products: "cloud-serverless {version}" <4> - elasticsearch-report: - output: "elasticsearch-{version}.yaml" + output: "serverless/{version}.yaml" <4> + output_products: "cloud-serverless {version}" <5> + elasticsearch-release: + output: "elasticsearch/{version}.yaml" output_products: "elasticsearch {version} {lifecycle}" ``` 1. The directory that contains changelog files. 2. The directory that contains changelog bundles. -3. If the `output` and `output_products` are omitted, the default path and file names are used. This example shows how you can use a `{version}` variable to customize the bundle's filename. -4. You can likewise set the bundle's product metadata, which affects the rules that are applied and the product and version titles that ultimately appear in the documentation. +3. Resolve the changelog files in the bundle rather than just referencing them. Otherwise, when you move or remove changelog files the bundle cannot be rendered. +4. If `output` is omitted, the default path and file names are used. This example shows how you can use a `{version}` variable to customize the bundle's filename. +5. The bundle's product metadata, which affects the rules that are applied and the product and version titles that ultimately appear in the documentation. If omitted, it's derived from all the changelogs in the bundle. ### Bundle by GitHub releases [profile-gh-release] @@ -96,6 +97,7 @@ For example: ```yaml bundle: + resolve: true profiles: agent-gh-release: source: github_release <1> @@ -140,7 +142,7 @@ bundle: products: "elasticsearch {version} ga" <3> output: "elasticsearch-{version}.yaml" # Infer the lifecycle from the version - elasticsearch-release: + elasticsearch-with-lifecycle: products: "elasticsearch {version} {lifecycle}" <4> output: "elasticsearch-{version}.yaml" output_products: "elasticsearch {version}" @@ -166,25 +168,30 @@ docs-builder changelog bundle The second argument accepts a version string, a promotion report URL or path, or a URL list file (a plain-text file with one fully-qualified GitHub URL per line). If you are using a `{version}` placeholder in the `output_products` or `output` fields, you must provide that value as well as your report or URL argument. -If the source of truth for what was shipped in each release is: +For example, if the source of truth for what was shipped in each release is: - a list of GitHub pull requests or issues: ```sh - # Bundle changelogs from a PR list ({version} → "2026-02-13") - docs-builder changelog bundle serverless-report 2026-02-13 ./prs.txt + # Bundle changelogs from a PR list buildkite report ({lifecycle} → "ga" inferred from "9.2.0") + docs-builder changelog bundle elasticsearch-release 9.2.0 ./prs.txt + ``` + ... where `prs.txt` is a newline delimited file with PR or issue URLs like this this: + ```txt + https://github.com/elastic/kibana/pull/123 + https://github.com/elastic/kibana/pull/456 ``` - - a buildkite promotion report: ```sh - # Bundle changelogs from a buildkite report ({lifecycle} → "ga" inferred from "9.2.0") - docs-builder changelog bundle elasticsearch-report 9.2.0 ./promotion-report.html + # Bundle changelogs from a buildkite report ({version} → "2026-02-13") + docs-builder changelog bundle serverless-report 2026-02-13 ./promotion-report.html ``` - automated release notes for GitHub releases: ```sh + # Bundle changelogs from a specific version of GitHub release notes docs-builder changelog bundle agent-gh-release 1.34.1 # Use "latest" to fetch the most recent release @@ -193,6 +200,10 @@ If the source of truth for what was shipped in each release is: Alternatively, use the [changelog gh-release](/cli/changelog/gh-release.md) command, which creates the changelogs and bundles at the same time. + :::{note} + This method requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. + ::: + - all changelog files that exist in a specific folder: ```sh @@ -202,18 +213,18 @@ If the source of truth for what was shipped in each release is: - all changelog files that match specific products, versions, and lifecycles: ```sh + # Bundle changelogs with partial dates + docs-builder changelog bundle serverless-monthly 2026-02 + # Bundle changelogs for a GA release ({lifecycle} → "ga" inferred from "9.2.0") - docs-builder changelog bundle elasticsearch-release 9.2.0 + docs-builder changelog bundle elasticsearch-with-lifecycle 9.2.0 # Bundle changelogs for a beta release ({lifecycle} → "beta" inferred from "9.2.0-beta.1") - docs-builder changelog bundle elasticsearch-release 9.2.0-beta.1 - - # Bundle changelogs with partial dates - docs-builder changelog bundle serverless-monthly 2026-02 + docs-builder changelog bundle elasticsearch-with-lifecycle 9.2.0-beta.1 ``` By default all changelogs that match the chosen source of truth are included in the bundle. -To apply additional filtering by the changelog type, areas, or products, add [rules.bundle](/contribute/configure-changelogs-ref.md#rules-bundle) configuration settings. +To apply additional filtering by the changelog type, areas, or products, add [bundle rules](#rules). :::{note} For profiles that use static patterns (without `{version}` or `{lifecycle}` placeholders), the second argument is still required but serves no functional purpose. You can pass any placeholder value. @@ -224,20 +235,33 @@ docs-builder changelog bundle release-all '*' docs-builder changelog bundle release-all 'unused' docs-builder changelog bundle release-all 'none' ``` + ::: -If you prefer to specify all the command options every time you run the command refer to [changelog bundle](/cli/changelog/bundle.md#option-based-examples). +If you don't want to use profiles and prefer to specify all the command options every time you run the command, refer to [Option-based examples](/cli/changelog/bundle.md#option-based-examples). ## Amend bundles [changelog-bundle-amend] -When you need to add changelogs to an existing bundle without modifying the original file, you can use the `docs-builder changelog bundle-amend` command to create amend bundles. +When you need to add changelogs to an existing bundle, you can use the `docs-builder changelog bundle-amend` command, which creates _amend bundles_. +For example: + +```sh +docs-builder changelog bundle-amend \ + ./docs/releases/9.3.0.yaml \ + --add "./docs/changelog/138723.yaml,./docs/changelog/1770424335.yaml" +``` + Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number. -When bundles are loaded (either via the `changelog render` command or the `{changelog}` directive), amend files are **automatically merged** with their parent bundles. +:::{note} +There is currently no command to **remove** changelogs from a bundle. You must edit the bundle file manually or else re-generate the bundle with an updated source of truth or a new rule that excludes the changelog. +::: + +When bundles are turned into docs (either via the `changelog render` command or the `{changelog}` directive), amend files are **automatically merged** with their parent bundles. The changelogs from all matching amend files are combined with the parent bundle's changelogs and the result is rendered as a single release. :::{warning} -If you explicitly list the amend bundles in the `--input` option of the `docs-builder changelog render` command, you'll get duplicate entries in the output files. List only the original bundles. +Don't explicitly list the amend bundles in the `--input` option of the `docs-builder changelog render` command--you'll get duplicate entries in the output files. List only the original/parent bundles. ::: For more details and examples, go to [](/cli/changelog/bundle-amend.md). @@ -255,80 +279,54 @@ Likewise, the `docs-builder changelog render` command fails for "unresolved" bun ::: You can use the `docs-builder changelog remove` command to remove changelogs. -It supports the same two modes as `changelog bundle`: you can specify all the command options or you can define "profiles" in the changelog configuration file. -In the command option mode, exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version`, or `--report`. - -Before deleting, the command automatically scans for bundles that still hold unresolved (`file:`) references to the matching changelog files. -If any are found, the command reports an error for each dependency. -This check prevents the `{changelog}` directive from failing at build time with missing file errors. -To proceed with removal even when unresolved bundle dependencies exist, use `--force`. - -To preview what would be removed without deleting anything, use `--dry-run`. -Bundle dependency conflicts are also reported in dry-run mode. - -### Removal with profiles [changelog-remove-profile] - -If your `changelog.yml` configuration file defines `bundle.profiles`, you can use those profiles with `changelog remove`. -This is the easiest way to remove exactly the changelogs that were included in a profile-based bundle. -The command syntax is: +If you created profiles, you can use them like this: ```sh docs-builder changelog remove ``` -For example, if you bundled with: - -```sh -docs-builder changelog bundle elasticsearch-release 9.2.0 -``` - -You can remove the same changelogs with: +For example, if the source of truth for what was shipped in each release is: -```sh -docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run -``` - -The command automatically discovers `changelog.yml` by checking `./changelog.yml` then `./docs/changelog.yml` relative to your current directory. -If no configuration file is found, the command returns an error with advice to create one or to run from the directory where the file exists. +- a list of GitHub pull requests or issues: -The `output`, `output_products`, `hide_features`, `link_allow_repos`, and `resolve` fields are bundle-specific and are always ignored for removal (along with other bundle-only settings that do not affect which changelog files match the filter). -Which other fields are used depends on the profile type: + ```sh + docs-builder changelog remove elasticsearch-release ./prs.txt + ``` -- Standard profiles: only the `products` field is used. The `repo` and `owner` fields are ignored (they only affect bundle output metadata). -- GitHub release profiles (`source: github_release`): `source`, `repo`, and `owner` are all used. The command fetches the PR list from the GitHub release identified by the version argument and removes changelogs whose `prs` field matches. +- a buildkite promotion report: -For example, given a GitHub release profile: + ```sh + docs-builder changelog remove serverless-report ./promotion-report.html + ``` -```sh -docs-builder changelog remove agent-gh-release v1.34.0 --dry-run -``` +- automated release notes for GitHub releases: -This fetches the PR list from the `v1.34.0` release (using the profile's `repo`/`owner` settings) and removes matching changelogs. + ```sh + docs-builder changelog remove agent-gh-release 1.34.1 + ``` -:::{note} -`source: github_release` profiles require a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. -::: + :::{note} + This method requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. + ::: -Profile-based removal is mutually exclusive with command options. -The only options allowed alongside a profile name are `--dry-run` and `--force`. +- all changelog files that exist in a specific folder: -You can also pass a promotion report URL, file path, or URL list file as the second argument, and the command removes changelogs whose pull request or issue URLs appear in the report: + ```sh + docs-builder changelog remove release-all '*' + ``` -```sh -docs-builder changelog remove elasticsearch-release https://buildkite.../promotion-report.html -docs-builder changelog remove serverless-release 2026-02 ./promotion-report.html -docs-builder changelog remove serverless-release 2026-02 ./prs.txt -``` +- all changelog files that match specific products, versions, and lifecycles: -### Removal with command options [changelog-remove-raw] + ```sh + docs-builder changelog remove serverless-monthly 2026-02 + ``` -You can alternatively remove changelogs based on their issues, pull requests, product metadata, or remove all changelogs from a folder. -Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, `--release-version` or `--report`. -When using a file for `--prs` or `--issues`, every line must be a fully-qualified GitHub URL. +Before deleting, the command automatically scans for bundles that still hold unresolved (`file:`) references to the matching changelog files. +If any are found, the command reports an error for each dependency. +This check prevents the `{changelog}` directive from failing at build time with missing file errors. +To proceed with removal even when unresolved bundle dependencies exist, use `--force`. -```sh -docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run -``` +To preview what would be removed without deleting anything, use `--dry-run`. For full option details, go to [](/cli/changelog/remove.md). @@ -373,65 +371,17 @@ rules: Product-specific rules override the global rules entirely—they do not merge. For details, refer to [](/contribute/configure-changelogs-ref.md#rules-bundle) and [](/contribute/configure-changelogs-ref.md#advanced-rule-examples). - -### Bundle changelogs from a GitHub release [changelog-bundle-profile-github-release] - -Set `source: github_release` on a profile to make `changelog bundle` fetch the PR list directly from a published GitHub release. - -This is equivalent to running `changelog bundle --release-version `, but fully configured in `changelog.yml` so you don't have to remember command-line flags. - -```yaml -bundle: - owner: elastic - profiles: - agent-gh-release: - source: github_release - repo: apm-agent-dotnet - output: "my-agents-{version}.yaml" - output_products: "apm-agent-dotnet {version} {lifecycle}" -``` - -Invoke the profile with a version tag or `latest`: - -```sh -docs-builder changelog bundle agent-gh-release 1.34.0 -docs-builder changelog bundle agent-gh-release latest -``` - -The `{version}` placeholder is substituted with the clean base version extracted from the release tag (for example, `v1.34.0` → `1.34.0`, `v1.34.0-beta.1` → `1.34.0`). The `{lifecycle}` placeholder is inferred from the **release tag** returned by GitHub, not from the argument you pass to the command: - -| Release tag | `{version}` | `{lifecycle}` | -|-------------|-------------|---------------| -| `v1.2.3` | `1.2.3` | `ga` | -| `v1.2.3-beta.1` | `1.2.3` | `beta` | -| `v1.2.3-preview.1` | `1.2.3` | `preview` | - -This differs from standard profiles, where `{lifecycle}` is inferred from the version string you type at the command line. - ### Bundle descriptions You can add introductory text to bundles using the `description` field. This text appears at the top of rendered changelogs, after the release heading but before the entry sections. -**Configuration locations:** +When using profiles, you can provide this information in: - `bundle.description`: Default description for all profiles - `bundle.profiles..description`: Profile-specific description (overrides the default) -**Placeholder support:** - -Bundle descriptions support these placeholders: - -- `{version}`: The resolved version string -- `{lifecycle}`: The resolved lifecycle (ga, beta, preview, etc.) -- `{owner}`: The GitHub repository owner -- `{repo}`: The GitHub repository name - -**Important**: When using `{version}` or `{lifecycle}` placeholders, you must ensure predictable substitution values: - -- **Option-based mode**: Requires `--output-products` when using placeholders -- **Profile-based mode**: Requires either a version argument (e.g., `bundle profile 9.2.0`) OR an `output_products` pattern in the profile configuration when using placeholders. If you invoke a profile with only a promotion report (e.g., `bundle profile ./report.html`), placeholders will fail unless `output_products` is configured. - -**Multiline descriptions in YAML:** +Bundle descriptions support these `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` substitution variables. +When using `{version}` or `{lifecycle}`, you must provide the necessary version argument in the command (for example, `bundle profile 9.2.0`) or define `output_products` in your configuration file. For complex descriptions with multiple paragraphs, lists, and links, use YAML literal block scalars with the `|` (pipe) syntax: @@ -451,40 +401,6 @@ bundle: The `|` (pipe) preserves line breaks and is ideal for Markdown-formatted text. Avoid using `>` (greater than) for descriptions as it folds line breaks into spaces, making lists and paragraphs difficult to format correctly. -**Command line usage:** - -For simple descriptions, use the `--description` option with regular quotes: - -```sh -docs-builder changelog bundle --all --description "This release includes new features." -``` - -For multiline descriptions on the command line, use ANSI-C quoting (`$'...'`) with `\n` for line breaks: - -```sh -docs-builder changelog bundle --all --description $'Enhanced release:\n\n- Performance improvements\n- Bug fixes' -``` - -`output_products` is optional. When omitted, the bundle products array is derived from the matched changelog files' own `products` fields — the same fallback used by all other profile types. Set `output_products` when you want a single clean product entry that reflects the release identity rather than the diverse metadata across individual changelog files, or to hardcode a lifecycle that cannot be inferred from the tag format: - -```yaml -# Produce one authoritative product entry instead of inheriting from changelog files -agent-gh-release: - source: github_release - repo: apm-agent-dotnet - output: "apm-agent-dotnet-{version}.yaml" - output_products: "apm-agent-dotnet {version} {lifecycle}" - -# Or hardcode the lifecycle when the tag format doesn't encode it -agent-gh-release-preview: - source: github_release - repo: apm-agent-dotnet - output: "apm-agent-dotnet-{version}-preview.yaml" - output_products: "apm-agent-dotnet {version} preview" -``` - -`source: github_release` is mutually exclusive with `products`, and a third positional argument (promotion report or URL list) is not accepted by this profile type. - ### Option-based bundling [changelog-bundle-options] You can specify only one of the following filter options: @@ -513,199 +429,6 @@ When you do not specify `--output`, the command writes the bundle to `bundle.out When you do not specify `--repo` or `--owner`, the command falls back to `bundle.repo` and `bundle.owner` in the changelog configuration, so you rarely need to pass these on the command line. --> -### Filter by product [changelog-bundle-product] - -You can use the `--input-products` option to create a bundle of changelogs that match the product details. -When using `--input-products`, you must provide all three parts: product, target, and lifecycle. -Each part can be a wildcard (`*`) to match any value. - -:::{tip} -If you use profile-based bundling, provide this information in the `bundle.profiles..products` field. -::: - -```sh -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](/cli/changelog/bundle.md#product-format). - -You can use wildcards in any of the three parts: - -```sh -# Bundle any changelogs that have exact matches for either of these clauses -docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 ga, elasticsearch 9.3.0 beta" - -# Bundle all elasticsearch changelogs regardless of target or lifecycle -docs-builder changelog bundle --input-products "elasticsearch * *" - -# Bundle all cloud-serverless 2025-12-02 changelogs with any lifecycle -docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 *" - -# Bundle any cloud-serverless changelogs with target starting with "2025-11-" and "ga" lifecycle -docs-builder changelog bundle --input-products "cloud-serverless 2025-11-* ga" - -# Bundle all changelogs (equivalent to --all) -docs-builder changelog bundle --input-products "* * *" -``` - -If you have changelog files that reference those product details, the command creates a file like this: - -```yaml -products: <1> -- product: cloud-serverless - target: 2025-12-02 -- product: cloud-serverless - target: 2025-12-06 -entries: -- file: - name: 1765495972-fixes-enrich-and-lookup-join-resolution-based-on-m.yaml - checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464 -- file: - name: 1765507778-break-on-fielddata-when-building-global-ordinals.yaml - checksum: 70d197d96752c05b6595edffe6fe3ba3d055c845 -``` - -1. By default these values match your `--input-products` (even if the changelogs have more products). -To specify different product metadata, use the `--output-products` option. - -### Filter by pull requests [changelog-bundle-pr] - -You can use the `--prs` option to create a bundle of the changelogs that relate to those pull requests. -You can provide either a comma-separated list of PRs (`--prs "https://github.com/owner/repo/pull/123,12345"`) or a path to a newline-delimited file (`--prs /path/to/file.txt`). -In the latter case, the file should contain one PR URL or number per line. - -Pull requests can be identified by a full URL (such as `https://github.com/owner/repo/pull/123`), a short format (such as `owner/repo#123`), or just a number (in which case you must also provide `--owner` and `--repo` options). - -```sh -docs-builder changelog bundle --prs "108875,135873,136886" \ <1> - --repo elasticsearch \ <2> - --owner elastic \ <3> - --output-products "elasticsearch 9.2.2 ga" <4> -``` - -1. The comma-separated list of pull request numbers to seek. -2. The repository in the pull request URLs. Not required when using full PR URLs, or when `bundle.repo` is set in the changelog configuration. -3. The owner in the pull request URLs. Not required when using full PR URLs, or when `bundle.owner` is set in the changelog configuration. -4. The product metadata for the bundle. If it is not provided, it will be derived from all the changelog product values. - -In Mode 3, the **rule context product** is the first alphabetically from `--output-products` (or from aggregated changelog products if omitted). To apply a different product's per-product rules, use a bundle whose `output_products` contains only that product (separate command or profile). - -If you have changelog files that reference those pull requests, the command creates a file like this: - -```yaml -products: -- product: elasticsearch - target: 9.2.2 - lifecycle: ga -entries: -- file: - name: 1765507819-fix-ml-calendar-event-update-scalability-issues.yaml - checksum: 069b59edb14594e0bc3b70365e81626bde730ab7 -- file: - name: 1765507798-convert-bytestransportresponse-when-proxying-respo.yaml - checksum: c6dbd4730bf34dbbc877c16c042e6578dd108b62 -- file: - name: 1765507839-use-ivf_pq-for-gpu-index-build-for-large-datasets.yaml - checksum: 451d60283fe5df426f023e824339f82c2900311e -``` - -### Filter by issues [changelog-bundle-issues] - -You can use the `--issues` option to create a bundle of changelogs that relate to those GitHub issues. -Provide either a comma-separated list of issues (`--issues "https://github.com/owner/repo/issues/123,456"`) or a path to a newline-delimited file (`--issues /path/to/file.txt`). -Issues can be identified by a full URL (such as `https://github.com/owner/repo/issues/123`), a short format (such as `owner/repo#123`), or just a number (in which case `--owner` and `--repo` are required — or set via `bundle.owner` and `bundle.repo` in the configuration). - -```sh -docs-builder changelog bundle --issues "12345,12346" \ - --repo elasticsearch \ - --owner elastic \ - --output-products "elasticsearch 9.2.2 ga" -``` - -### Filter by pull request or issue file [changelog-bundle-file] - -If you have a file that lists pull requests (such as PRs associated with a GitHub release), you can pass it to `--prs`. -For example, if you have a file that contains full pull request URLs like this: - -```txt -https://github.com/elastic/elasticsearch/pull/108875 -https://github.com/elastic/elasticsearch/pull/135873 -https://github.com/elastic/elasticsearch/pull/136886 -https://github.com/elastic/elasticsearch/pull/137126 -``` - -You can use the `--prs` option with the file path to create a bundle of the changelogs that relate to those pull requests. -You can also combine multiple `--prs` options: - -```sh -./docs-builder changelog bundle \ - --prs "https://github.com/elastic/elasticsearch/pull/108875,135873" \ <1> - --prs test/9.2.2.txt \ <2> - --output-products "elasticsearch 9.2.2 ga" <3> - --resolve <4> -``` - -1. Comma-separated list of pull request URLs or numbers. -2. The path for the file that lists the pull requests. If the file contains only PR numbers, you must add `--repo` and `--owner` command options. -3. The product metadata for the bundle. If it is not provided, it will be derived from all the changelog product values. -4. Optionally include the contents of each changelog in the output file. - -:::{tip} -You can use these files with profile-based bundling too. Refer to [](/cli/changelog/bundle.md). -::: - -If you have changelog files that reference those pull requests, the command creates a file like this: - -```yaml -products: -- product: elasticsearch - target: 9.2.2 - lifecycle: ga -entries: -- file: - name: 1765507778-break-on-fielddata-when-building-global-ordinals.yaml - checksum: 70d197d96752c05b6595edffe6fe3ba3d055c845 - type: bug-fix - title: Break on FieldData when building global ordinals - products: - - product: elasticsearch - areas: - - Aggregations - prs: - - https://github.com/elastic/elasticsearch/pull/108875 -... -``` - -:::{note} -When a changelog matches multiple `--input-products` filters, it appears only once in the bundle. This deduplication applies even when using `--all` or `--prs`. -::: - -### Filter by GitHub release notes [changelog-bundle-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), you can use the `--release-version` option to derive the PR list from those release notes. -For example: - -```sh -docs-builder changelog bundle \ - --release-version v1.34.0 \ - --repo apm-agent-dotnet --owner elastic <1> -``` - -1. The repo and repo owner are used to fetch the release and follow these rules of precedence: - -- Repo: `--repo` flag > `bundle.repo` in `changelog.yml` (one source is required) -- Owner: `--owner` flag > `bundle.owner` in `changelog.yml` > `elastic` - -This command creates a bundle of changelogs that match the list of PRs found in the `v1.34.0` GitHub release notes. - -The bundle's product metadata is inferred automatically from the release tag and repository name; you can override that behavior with the `--output-products` option. - -:::{tip} -If you are not creating changelogs when you create your pull requests, consider the `docs-builder changelog gh-release` command as a one-shot alternative to the `changelog add` and `changelog bundle` commands. -It 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) -::: - ### Hide features [changelog-bundle-hide-features] You can use the `--hide-features` option to embed feature IDs that should be hidden when the bundle is rendered. This is useful for features that are not yet ready for public documentation. From b5421cd3921535c9f4fbac1779810974a6148761 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 5 May 2026 16:00:57 -0700 Subject: [PATCH 4/6] Remove more redundancy --- docs/cli/changelog/bundle.md | 171 +++++++++---------- docs/contribute/bundle-changelogs.md | 176 +++++++------------- docs/contribute/configure-changelogs-ref.md | 39 ++++- docs/contribute/configure-changelogs.md | 7 +- docs/contribute/create-changelogs.md | 7 +- 5 files changed, 193 insertions(+), 207 deletions(-) diff --git a/docs/cli/changelog/bundle.md b/docs/cli/changelog/bundle.md index 809ac8ba2..3a1e0628f 100644 --- a/docs/cli/changelog/bundle.md +++ b/docs/cli/changelog/bundle.md @@ -86,11 +86,15 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp : - **Profile-based mode**: Requires either a version argument OR `output_products` in the profile configuration `--hide-features ` -: Optional: A list of feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs. +: Optional: A list of feature IDs (comma-separated) or a path to a newline-delimited file containing feature IDs. : Can be specified multiple times. : Adds a `hide-features` list to the bundle. : When the bundle is rendered (by the `changelog render` command or `{changelog}` directive), changelogs with matching `feature-id` values will be commented out of the documentation. +:::{note} +The `--hide-features` option on the `render` command and the `hide-features` field in bundles are **combined**. If you specify `--hide-features` on both the `bundle` and `render` commands, all specified features are hidden. The `{changelog}` directive automatically reads `hide-features` from all loaded bundles and applies them. +::: + `--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](#product-format). @@ -103,11 +107,12 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp - `"* * *"` - match all changelogs (equivalent to `--all`) :::{note} -The `--input-products` option determines which changelog files are gathered for consideration. **`rules.bundle` is not disabled** when you use `--input-products` — global `include_products` / `exclude_products`, type/area rules, and (when configured) per-product rules still run **after** matching, unless your configuration is in no-filtering mode per [Bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). The only “mutually exclusive” pairing on this command is **profile-based** bundling versus **option-based** flags (see [Usage](#usage)), not `--input-products` versus `rules.bundle`. +The `--input-products` option determines which changelog files are gathered for consideration. +Bundle rules are not turned off when you use `--input-products`-- they run **after** matching, unless your configuration is in no-filtering mode per [Bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). ::: `--issues ` -: Filter by issue URLs (comma-separated), or a path to a newline-delimited file. Can be specified multiple times. +: Include changelogs for the specified issue URLs (comma-separated), or a path to a newline-delimited file. Can be specified multiple times. : Each occurrence can be either comma-separated issues ( `--issues "https://github.com/owner/repo/issues/123,456"`) or a file path (for example `--issues /path/to/file.txt`). : When using a file, every line must be a fully-qualified GitHub issue URL such as `https://github.com/owner/repo/issues/123`. Bare numbers and short forms are not allowed in files. @@ -123,31 +128,33 @@ The `--input-products` option determines which changelog files are gathered for : 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). +: When `rules.bundle.products` per-product overrides are configured, `--output-products` also supplies the product IDs used to determine the **rule context product** (if there are multiple, the first ID alphabetically is used). Refer to [Product-specific bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle-products). + +:::{tip} +Though technically optional, it is strongly recommended to set `--output-products` ( or `output_products` for profiles) so that you have a single clean product entry that reflects the context of the release. +::: `--no-release-date` : Optional: Skip auto-population of release date in the bundle. : By default, bundles are created with a `release-date` field set to today's date (UTC) or the GitHub release published date when using `--release-version`. : Mutually exclusive with `--release-date`. -: **Not available in profile mode** — use bundle configuration instead. `--release-date ` : Optional: Explicit release date for the bundle in YYYY-MM-DD format. : Overrides the default auto-population behavior (today's date or GitHub release published date). : Mutually exclusive with `--no-release-date`. -: **Not available in profile mode** — use bundle configuration instead. `--owner ` : Optional: The GitHub repository owner, required when pull requests or issues are specified as numbers. : Precedence: `--owner` flag > `bundle.owner` in `changelog.yml` > `elastic`. `--prs ` -: Filter by pull request URLs (comma-separated) or a path to a newline-delimited file. Can be specified multiple times. +: Include changelogs for the specified pull request URLs (comma-separated) or a path to a newline-delimited file. Can be specified multiple times. : Each occurrence can be either comma-separated PRs (for example `--prs "https://github.com/owner/repo/pull/123,6789"`) or a file path (for example `--prs /path/to/file.txt`). : When using a file, every line must be a fully-qualified GitHub PR URL such as `https://github.com/owner/repo/pull/123`. Bare numbers and short forms are not allowed in files. -`--release-version ` -: GitHub release tag to use as a source of pull requests (for example, `"v9.2.0"` or `"latest"`). +`--release-version ` +: Bundle changelogs for the pull requests in GitHub release notes. For example, the tag can be `"v9.2.0"` or `"latest"`. : When specified, the command fetches the release from GitHub, parses PR references from the release notes, and uses them as the bundle filter. Only automated GitHub release notes (the default format or [Release Drafter](https://github.com/release-drafter/release-drafter) format) are supported at this time. : Requires repo (`--repo` or `bundle.repo` in `changelog.yml`) and owner (`--owner` flag > `bundle.owner` in `changelog.yml` > `elastic`) details. : When `--output-products` is not specified, the products array in the bundle is derived from the matched changelog files' own `products` fields, consistent with all other filter options. @@ -157,14 +164,22 @@ The `--input-products` option determines which changelog files are gathered for : Falls back to `bundle.repo` in `changelog.yml` when not specified; if that is also absent, the product ID is used. `--report ` -: Filter by pull requests extracted from a promotion report. Accepts a URL or a local file path. +: Include changelogs based on the pull requests in a promotion report. Accepts a URL or a local file path. : The report can be an HTML page from Buildkite or any file containing GitHub PR URLs. `--resolve` : Optional: Copy the contents of each changelog file into the entries array. : By default, the bundle contains only the file names and checksums. -## Output files +## File paths and filenames [output-files] + +**Input directory** (where changelog YAML files are read from) follows the same fallback for both modes, minus the explicit CLI override that is forbidden in profile mode: + +| Priority | Profile-based | Option-based | +|----------|---------------|--------------| +| 1 | `bundle.directory` in `changelog.yml` | `--directory` CLI option | +| 2 | Current working directory | `bundle.directory` in `changelog.yml` | +| 3 | — | Current working directory | Both modes use the same ordered fallback to determine where to write the bundle. The first value that is set wins: @@ -178,14 +193,6 @@ Both modes use the same ordered fallback to determine where to write the bundle. | 4 | Current working directory | `bundle.directory` in `changelog.yml` | | 5 | — | Current working directory | -**Input directory** (where changelog YAML files are read from) follows the same fallback for both modes, minus the explicit CLI override that is forbidden in profile mode: - -| Priority | Profile-based | Option-based | -|----------|---------------|--------------| -| 1 | `bundle.directory` in `changelog.yml` | `--directory` CLI option | -| 2 | Current working directory | `bundle.directory` in `changelog.yml` | -| 3 | — | Current working directory | - **Bundle filename** is determined by the `bundle.profiles..output` setting (profile-based) or defaults to `changelog-bundle.yaml` (both modes). The profile `output` setting can include additional path segments. For example: `"stack/kibana-{version}.yaml"`. @@ -303,15 +310,16 @@ Only automated GitHub release notes (the default format or [Release Drafter](htt ```sh docs-builder changelog bundle \ - --release-version v1.34.0 \ - --repo apm-agent-dotnet \ <1> - --owner elastic <2> - --output-products "apm-agent-dotnet 1.34.0 ga" <3> + --release-version v1.34.0 \ <1> + --repo apm-agent-dotnet \ <2> + --owner elastic <3> + --output-products "apm-agent-dotnet 1.34.0 ga" <4> ``` -1. You must specify `--repo` or set `bundle.repo` in the changelog configuration file. -2. If you don't specify `--owner`, it uses `bundle.owner` in the changelog configuration or else defaults to `elastic`. -3. The bundle's product metadata is inferred automatically from the release tag and repository name; you can override that behavior with the `--output-products` option. +1. The tag value that is used in the `GET /repos/{owner}/{repo}/releases/tags/{tag}` releases API. +2. You must specify `--repo` or set `bundle.repo` in the changelog configuration file. +3. If you don't specify `--owner`, it uses `bundle.owner` in the changelog configuration or else defaults to `elastic`. +4. The bundle's product metadata is inferred automatically from the release tag and repository name; you can override that behavior with the `--output-products` option. :::{note} `--release-version` requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. @@ -524,17 +532,52 @@ Refer to [](/contribute/bundle-changelogs.md#create-profiles) for examples. ### Lifecycle inference [lifecycle-inference] -#### Standard profiles +The way that lifecycle values are inferred varies between [GitHub release profiles](#lifecycles-github) and [standard profiles](#lifecycles-standard). -If your configuration file defines a standard profile (that is to say, not a GitHub release profile), the lifecycle is inferred from the version string you pass as the second argument: +#### GitHub release profiles [lifecycles-github] -| Version argument | Inferred lifecycle | -|------------------|--------------------| -| `9.2.0` | `ga` | -| `9.2.0-rc.1` | `ga` | -| `9.2.0-beta.1` | `beta` | -| `9.2.0-alpha.1` | `preview` | -| `9.2.0-preview.1` | `preview` | +For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is derived from the full release tag name and `{version}` is the base version extracted from that same tag. +For example: + +| Release tag | `{version}` | `{lifecycle}` | +|-------------|-------------|---------------| +| `v1.2.3` | `1.2.3` | `ga` | +| `v1.2.3-beta.1` | `1.2.3` | `beta` | +| `v1.2.3-preview.1` | `1.2.3` | `preview` | + +If the lifecycle you want to advertise cannot be inferred from the tag format — for example, because your team uses clean tags like `v1.34.1` even for pre-releases — hardcode the lifecycle directly in `output_products` instead of using the `{lifecycle}` placeholder: + +```yaml +# Instead of relying on {lifecycle} inference, hardcode the lifecycle +gh-release: + source: github_release + repo: apm-agent-dotnet + output: "apm-agent-dotnet-{version}.yaml" + output_products: "apm-agent-dotnet {version} preview" +``` + +You can invoke the profile with commands like this: + +```sh +# Bundle changelogs using the PR list from a GitHub release (source: github_release) +docs-builder changelog bundle gh-release v1.2.3 + +# Use "latest" to fetch the most recent release +docs-builder changelog bundle gh-release latest +``` + +#### Standard profiles [lifecycles-standard] + +If your configuration file defines a standard profile (that is to say, not a GitHub release profile), the `{version}` is copied verbatim from your command argument and the `{lifecycle}` is derived from that value. +For example: + +| Version argument | `{version}` | `{lifecycle}` | +|------------------|-------------|---------------| +| `9.2.0` | `9.2.0` | `ga` | +| `9.2.0-rc.1` | `9.2.0-rc.1` | `ga` | +| `9.2.0-beta.1` | `9.2.0-beta.1` | `beta` | +| `9.2.0-alpha.1` | `9.2.0-alpha.1` | `preview` | +| `9.2.0-preview.1` | `9.2.0-preview.1` | `preview` | For more information about acceptable product and lifecycle values, go to [Product format](#product-format). @@ -556,61 +599,13 @@ docs-builder changelog bundle serverless-report 2026-02-13 ./promotion-report.ht # Same using a URL list file instead of an HTML promotion report docs-builder changelog bundle serverless-report 2026-02-13 ./prs.txt - -# Bundle changelogs using the PR list from a GitHub release (source: github_release) -docs-builder changelog bundle elasticsearch-gh-release 9.2.0 - -# Use "latest" to fetch the most recent release -docs-builder changelog bundle elasticsearch-gh-release latest ``` -:::{warning} -**Placeholder validation**: If your profile uses `{version}` or `{lifecycle}` placeholders in the description, you must ensure predictable substitution values: +For profiles that use static patterns (without `{version}` or `{lifecycle}` placeholders), the second argument is still required but serves no functional purpose. You can pass any placeholder value: ```sh -# ✅ Good: Version provided for placeholder substitution -docs-builder changelog bundle elasticsearch-release 9.2.0 ./report.html - -# ❌ Bad: No version, placeholders will fail unless profile has output_products -docs-builder changelog bundle elasticsearch-release ./report.html -``` - -To fix the second case, either provide a version argument or add an `output_products` pattern to your profile: - -```yaml -bundle: - profiles: - elasticsearch-release: - products: "elasticsearch * *" - output_products: "elasticsearch {version}" # Enables placeholder substitution - description: "Download: https://github.com/{owner}/{repo}/releases/tag/v{version}" -``` - -::: - -#### GitHub release profiles - -For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is inferred from the release tag returned by GitHub (not the argument you pass to the command). -This means the pre-release suffix on the tag drives the lifecycle value: - -| Release tag | `{version}` | `{lifecycle}` | -|-------------|-------------|---------------| -| `v1.2.3` | `1.2.3` | `ga` | -| `v1.2.3-beta.1` | `1.2.3` | `beta` | -| `v1.2.3-preview.1` | `1.2.3` | `preview` | - -This differs from standard profiles, where lifecycle is inferred from the version argument you type. -For `source: github_release`, the `{version}` placeholder always uses the clean base version (stripped of any pre-release suffix), while `{lifecycle}` reflects the actual tag format. - -If the lifecycle you want to advertise cannot be inferred from the tag format — for example, because your team uses clean tags like `v1.34.1` even for pre-releases — hardcode the lifecycle directly in `output_products` instead of using the `{lifecycle}` placeholder: - -```yaml -# Instead of relying on {lifecycle} inference, hardcode the lifecycle -gh-release: - source: github_release - repo: apm-agent-dotnet - output: "apm-agent-dotnet-{version}.yaml" - output_products: "apm-agent-dotnet {version} preview" +# Profile with static patterns - second argument unused but required +docs-builder changelog bundle release-all '*' +docs-builder changelog bundle release-all 'unused' +docs-builder changelog bundle release-all 'none' ``` - - \ No newline at end of file diff --git a/docs/contribute/bundle-changelogs.md b/docs/contribute/bundle-changelogs.md index a5a34a865..3849850d5 100644 --- a/docs/contribute/bundle-changelogs.md +++ b/docs/contribute/bundle-changelogs.md @@ -46,12 +46,14 @@ You can: The latter method is more convenient and consistent for repetitive workflows, therefore it's the recommended method described here. -For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) and [](/contribute/configure-changelogs-ref.md). - -:::{note} You must create profiles that match your chosen source of truth. + +:::{tip} +It is strongly recommended to set `output_products` in your profile so your bundles have a single top-level product entry that provides the context of the release. This context is particularly important if you'll be [applying bundle rules](#rules). ::: +For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) and [](/contribute/configure-changelogs-ref.md). + ### Bundle by report or URL list [profile-url] If the source of truth for what was shipped in each release is: @@ -108,7 +110,7 @@ bundle: ``` 1. This profile fetches the PR list from the GitHub release notes for the version tag specified in the command. -2. For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is inferred from the release tag returned by GitHub (not the argument you pass to the command). For example, if the release tag is `v1.34.1-preview.1` the lifecycle is `preview`. Refer to [](/cli/changelog/bundle.md#lifecycle-inference) for more details. +2. For `source: github_release` profiles, the `{lifecycle}` placeholder in `output` and `output_products` is inferred from full release tag name. For example, if the release tag is `v1.34.1-preview.1` the lifecycle is `preview`. Refer to [](/cli/changelog/bundle.md#lifecycle-inference) for more details. ### Bundle by folder or changelog product @@ -173,14 +175,17 @@ For example, if the source of truth for what was shipped in each release is: - a list of GitHub pull requests or issues: ```sh - # Bundle changelogs from a PR list buildkite report ({lifecycle} → "ga" inferred from "9.2.0") + # Bundle changelogs from a PR list ({lifecycle} → "ga" inferred from "9.2.0") docs-builder changelog bundle elasticsearch-release 9.2.0 ./prs.txt ``` + ... where `prs.txt` is a newline delimited file with PR or issue URLs like this this: + ```txt https://github.com/elastic/kibana/pull/123 https://github.com/elastic/kibana/pull/456 ``` + - a buildkite promotion report: ```sh @@ -191,8 +196,8 @@ For example, if the source of truth for what was shipped in each release is: - automated release notes for GitHub releases: ```sh - # Bundle changelogs from a specific version of GitHub release notes - docs-builder changelog bundle agent-gh-release 1.34.1 + # Bundle changelogs from the release notes of a specific GitHub tag + docs-builder changelog bundle agent-gh-release v1.34.1 # Use "latest" to fetch the most recent release docs-builder changelog bundle agent-gh-release latest @@ -224,20 +229,13 @@ For example, if the source of truth for what was shipped in each release is: ``` By default all changelogs that match the chosen source of truth are included in the bundle. -To apply additional filtering by the changelog type, areas, or products, add [bundle rules](#rules). - -:::{note} -For profiles that use static patterns (without `{version}` or `{lifecycle}` placeholders), the second argument is still required but serves no functional purpose. You can pass any placeholder value. - -```sh -# Profile with static patterns - second argument unused but required -docs-builder changelog bundle release-all '*' -docs-builder changelog bundle release-all 'unused' -docs-builder changelog bundle release-all 'none' -``` +:::{tip} +It is strongly recommended to pull all of the content from each changelog into the bundle; otherwise you can't move or remove your changelogs. If your bundle contains only references to the files, add set [bundle.resolve](/contribute/configure-changelogs-ref.md#bundle-basic) to true and re-generate your bundle. ::: +To apply additional filtering by the changelog type, areas, or products, add [bundle rules](#rules). + If you don't want to use profiles and prefer to specify all the command options every time you run the command, refer to [Option-based examples](/cli/changelog/bundle.md#option-based-examples). ## Amend bundles [changelog-bundle-amend] @@ -332,15 +330,19 @@ For full option details, go to [](/cli/changelog/remove.md). ## Examples +The following sections provide more details about optional and advanced steps. + ### Apply bundle rules [rules] -:::{tip} +:::{important} Not everything that was shipped in a release and has a changelog necessarily belongs in the release bundle. ::: If you want to automatically include or exclude changelogs from bundles based on their areas, types, or products, you can accomplish this with rules in your changelog configuration file. +Bundle rules run as a secondary stage after the candidate changelogs are collected (for example, based on a PR list, promotion report, or other valid source of truth). + For example, you might choose to omit `other` or `docs` types of changelogs. -Or you might choose to omit all changelogs related to specific features (`areas`) from a specific product's release bundles. +Or you might choose to omit all changelogs related to specific features (`areas`) from a product's release bundles. You can define rules at the global level (applies to all products) like this: @@ -369,114 +371,64 @@ rules: ``` Product-specific rules override the global rules entirely—they do not merge. -For details, refer to [](/contribute/configure-changelogs-ref.md#rules-bundle) and [](/contribute/configure-changelogs-ref.md#advanced-rule-examples). - -### Bundle descriptions - -You can add introductory text to bundles using the `description` field. This text appears at the top of rendered changelogs, after the release heading but before the entry sections. - -When using profiles, you can provide this information in: +For details, refer to [](/contribute/configure-changelogs-ref.md#rules-bundle) and [](/contribute/configure-changelogs-ref.md#advanced-rule-examples). -- `bundle.description`: Default description for all profiles -- `bundle.profiles..description`: Profile-specific description (overrides the default) - -Bundle descriptions support these `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` substitution variables. -When using `{version}` or `{lifecycle}`, you must provide the necessary version argument in the command (for example, `bundle profile 9.2.0`) or define `output_products` in your configuration file. +### Hide features [changelog-bundle-hide-features] -For complex descriptions with multiple paragraphs, lists, and links, use YAML literal block scalars with the `|` (pipe) syntax: +Changelogs have an optional `feature-id` field that you can use to associate the change with a specific feature or project. +If there are features or projects that are not yet ready for public documentation, you can list those IDs in the [`hide_features`](/contribute/configure-changelogs-ref.md#bundle-profiles) setting: ```yaml bundle: - description: | - This release includes significant improvements: - - - Enhanced performance - - Bug fixes and stability improvements - - New features for better user experience - - For security updates, go to [security announcements](https://example.com/docs). - - Download the release binaries: https://github.com/{owner}/{repo}/releases/tag/v{version} + directory: docs/changelog + output_directory: docs/releases + repo: elasticsearch + owner: elastic + resolve: true + profiles: + serverless-report: + output: "serverless/{version}.yaml" + output_products: "cloud-serverless {version}" + hide_features: <1> + - feature-flag-1 + - feature-flag-2 ``` -The `|` (pipe) preserves line breaks and is ideal for Markdown-formatted text. Avoid using `>` (greater than) for descriptions as it folds line breaks into spaces, making lists and paragraphs difficult to format correctly. - -### Option-based bundling [changelog-bundle-options] - -You can specify only one of the following filter options: - -- `--all`: Include all changelogs from the directory. -- `--input-products`: Include changelogs for the specified products. Refer to [Filter by product](#changelog-bundle-product). -- `--prs`: Include changelogs for the specified pull request URLs, or a path to a newline-delimited file. When using a file, every line must be a fully-qualified GitHub URL such as `https://github.com/owner/repo/pull/123`. Go to [Filter by pull requests](#changelog-bundle-pr). -- `--issues`: Include changelogs for the specified issue URLs, or a path to a newline-delimited file. When using a file, every line must be a fully-qualified GitHub URL such as `https://github.com/owner/repo/issues/123`. Go to [Filter by issues](#changelog-bundle-issues). -- `--release-version`: Bundle changelogs for the pull requests in GitHub release notes. Refer to [Bundle by GitHub release](#changelog-bundle-release-version). -- `--report`: Include changelogs whose pull requests appear in a promotion report. Accepts a URL or a local file path to an HTML report. - -`rules.bundle` in `changelog.yml` is **not** mutually exclusive with these options: it runs as a **second stage** after the primary filter matches entries (for example, `--input-products` gathers changelogs, then global or per-product bundle rules may exclude some). The only mutually exclusive pairing is **profile-based** versus **option-based** invocation. See [bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle). - -By default, the output file contains only the changelog file names and checksums. -To change this behavior, set `bundle.resolve` to `true` in the changelog configuration file or use the `--resolve` command option. - -:::{tip} -If you plan to use [changelog directives](/contribute/publish-changelogs.md#changelog-directive), it is recommended to pull all of the content from each changelog into the bundle; otherwise you can't delete your changelogs. -If you likewise want to regenerate your [Asciidoc or Markdown files](/contribute/publish-changelogs.md#render-changelogs) after deleting your changelogs, it's only possible if you have "resolved" bundles. -::: - - - -### Hide features [changelog-bundle-hide-features] - -You can use the `--hide-features` option to embed feature IDs that should be hidden when the bundle is rendered. This is useful for features that are not yet ready for public documentation. - -```sh -docs-builder changelog bundle \ - --input-products "elasticsearch 9.3.0 *" \ - --hide-features "feature:hidden-api,feature:experimental" \ <1> - --output /path/to/bundles/9.3.0.yaml -``` +1. The feature identifiers to hide. -1. Feature IDs to hide. Changelogs with matching `feature-id` values will be commented out when rendered. +When you use this profile to create a bundle, the list is carried forward into its metadata. +Any changelogs with matching `feature-id` values are commented out when you publish the bundle. - +### Hide private links -The bundle output will include a `hide-features` field: +A changelog can reference multiple pull requests and issues in its `prs` and `issues` fields. +You can allowlist links to certain repos with the `link_allow_repos` setting: ```yaml -products: -- product: elasticsearch - target: 9.3.0 -hide-features: - - feature:hidden-api - - feature:experimental -entries: -- file: - name: 1765495972-new-feature.yaml - checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464 +bundle: + directory: docs/changelog + output_directory: docs/releases + repo: elasticsearch + owner: elastic + resolve: true + link_allow_repos: <1> + - elastic/elasticsearch + - elastic/kibana + - elastic/roadmap ``` -When this bundle is rendered (either via the `changelog render` command or the `{changelog}` directive), changelogs with `feature-id` values matching any of the listed features will be commented out in the output. +1. Only links to these owner/repo pairs are shown in the release docs. Others are rewritten to `# PRIVATE:` sentinels. -:::{note} -The `--hide-features` option on the `render` command and the `hide-features` field in bundles are **combined**. If you specify `--hide-features` on both the `bundle` and `render` commands, all specified features are hidden. The `{changelog}` directive automatically reads `hide-features` from all loaded bundles and applies them. -::: - -### Hide private links +There are no implicit values for this setting. You must list every repo whose links should appear, including the current repo. +When this setting is omitted entirely, no link filtering is applied. +For more details, refer to [PR and issue link allowlist](/cli/changelog/bundle.md#link-allowlist). -A changelog can reference multiple pull requests and issues in the `prs` and `issues` array fields. +:::{tip} +You must set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained) in order to hide the private links. The bundle's changelog entries are sanitized but the individual changelog files are unchanged. +::: -To comment out links that are not in your allowlist in all changelogs in your bundles, refer to [changelog bundle](/cli/changelog/bundle.md#link-allowlist). +If you are working in a private repo and do not want any pull request or issue links to appear (even if they target a public repo), you can also configure link visibiblity in the [changelog directive](/syntax/changelog.md#hide-links) and [changelog render](/cli/changelog/render.md) command. -If you are working in a private repo and do not want any pull request or issue links to appear (even if they target a public repo), you also have the option to configure link visibiblity in the [changelog directive](/syntax/changelog.md) and [changelog render](/cli/changelog/render.md) command. +## Next steps -:::{tip} -You must run the `docs-builder changelog bundle` command with the `--resolve` option or set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained) in order to hide the private links. -::: +After you've created release bundles, you can use them to generate [release docs](/contribute/publish-changelogs.md). diff --git a/docs/contribute/configure-changelogs-ref.md b/docs/contribute/configure-changelogs-ref.md index bfd1ac782..0ee785f40 100644 --- a/docs/contribute/configure-changelogs-ref.md +++ b/docs/contribute/configure-changelogs-ref.md @@ -30,6 +30,12 @@ These are the main configuration sections: Configures directory paths, GitHub repository defaults, and named profiles for bundle operations. These settings are separate from `rules.bundle` filtering. +Refer to: + +- [Basic bundle settings](#bundle-basic) +- [Bundle descriptions](#bundle-descriptions) +- [Bundle profiles](#bundle-profiles) + ### Basic settings [bundle-basic] Controls bundle-level behavior. @@ -40,7 +46,6 @@ These settings are relevant to one or all of the `changelog bundle`, `changelog | Setting | Description | | ------------------------- | ----------- | -| `bundle.description` | Default template for bundle descriptions. Supports `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` placeholders. | | `bundle.directory` | Input directory containing changelog YAML files (default: `docs/changelog`). | | `bundle.link_allow_repos` | List of `owner/repo` pairs whose PR/issue links are preserved. When set (including empty `[]`), links to unlisted repos become `# PRIVATE:` sentinels. Requires `bundle.resolve: true` | | `bundle.output_directory` | Output directory for bundled files (default: `docs/releases`). | @@ -58,6 +63,36 @@ When `bundle.link_allow_repos` is omitted, no link filtering occurs. - For public repos, add your `owner/repo` to the list at a minimum. ::: +### Bundle descriptions [bundle-descriptions] + +You can add introductory text to bundles using the `description` field. This text appears at the top of rendered changelogs, after the release heading but before the entry sections. + +When using profiles, you can provide this information in: + +- `bundle.description`: Default description for all profiles +- `bundle.profiles..description`: Profile-specific description (overrides the default) + +Bundle descriptions support these `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` substitution variables. +When using `{version}` or `{lifecycle}`, you must provide the necessary version argument in the command (for example, `bundle profile 9.2.0`) or define `output_products` in your configuration file. + +For complex descriptions with multiple paragraphs, lists, and links, use YAML literal block scalars with the `|` (pipe) syntax: + +```yaml +bundle: + description: | + This release includes significant improvements: + + - Enhanced performance + - Bug fixes and stability improvements + - New features for better user experience + + For security updates, go to [security announcements](https://example.com/docs). + + Download the release binaries: https://github.com/{owner}/{repo}/releases/tag/v{version} +``` + +The `|` (pipe) preserves line breaks and is ideal for Markdown-formatted text. Avoid using `>` (greater than) for descriptions as it folds line breaks into spaces, making lists and paragraphs difficult to format correctly. + ### Bundle profiles [bundle-profiles] Named profiles enable you to run commands repeatedly with consistent options. @@ -66,7 +101,7 @@ They work with both `changelog bundle` and `changelog remove` commands. These settings are located in the `bundle.profiles.` section of the configuration file: `description` -: Overrides the global [bundle.description](#bundle-basic). +: Overrides the global [bundle.description](#bundle-descriptions). `hide_features` : Feature IDs to mark as hidden in the bundle. diff --git a/docs/contribute/configure-changelogs.md b/docs/contribute/configure-changelogs.md index 244cef86c..35ef796b1 100644 --- a/docs/contribute/configure-changelogs.md +++ b/docs/contribute/configure-changelogs.md @@ -104,12 +104,11 @@ pivot: For the most up-to-date changelog configuration options, refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml). -## Use a changelog configuration file [usage] +## Next steps [usage] After you've created a config file, all subsequent changelog commands can use it. By default, they look for `changelog.yml` by checking `./changelog.yml` then `./docs/changelog.yml` relative to your current directory. Most changelog commands allow you to specify a different path with the `--config` option. -For specific details about the usage and impact of the configuration file, refer to the [changelog commands](/cli/changelog/index.md). - -The [changelog directive](/syntax/changelog.md) also uses the changelog configuration file and you can specify a non-default path if necessary. \ No newline at end of file +1. Start [creating changelog files](/contribute/create-changelogs.md). +1. You might need to make further changes to your configuration file after you've performed a few tests. Likewise you might need to add bundle settings or profiles when you're ready to [create release bundles](/contribute/bundle-changelogs.md). diff --git a/docs/contribute/create-changelogs.md b/docs/contribute/create-changelogs.md index 282171521..6ce147d8f 100644 --- a/docs/contribute/create-changelogs.md +++ b/docs/contribute/create-changelogs.md @@ -174,4 +174,9 @@ 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) \ 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). + +## Next steps + +After you've created a changelog files, you can gather them into [release bundles](/contribute/bundle-changelogs.md). +The release bundles are ultimately used to generate [release docs](/contribute/publish-changelogs.md). \ No newline at end of file From 11a31fb0e21dd03e4b7ea686aa769274c2899917 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Tue, 5 May 2026 16:24:25 -0700 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- config/changelog.example.yml | 2 +- docs/contribute/bundle-changelogs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/config/changelog.example.yml b/config/changelog.example.yml index 4288edd5b..e02f65074 100644 --- a/config/changelog.example.yml +++ b/config/changelog.example.yml @@ -151,7 +151,7 @@ pivot: # - Comma-separated string: "value1, value2, value3" # - YAML list: [value1, value2, value3] # -# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/contribute/configure-changelogs-ref#rules). +# For details and examples, refer to the [rules documentation](https://github.com/elastic/docs-builder/blob/main/docs/contribute/configure-changelogs-ref.md#rules). rules: # match: any diff --git a/docs/contribute/bundle-changelogs.md b/docs/contribute/bundle-changelogs.md index 3849850d5..b3c175c51 100644 --- a/docs/contribute/bundle-changelogs.md +++ b/docs/contribute/bundle-changelogs.md @@ -427,7 +427,7 @@ For more details, refer to [PR and issue link allowlist](/cli/changelog/bundle.m You must set `bundle.resolve` to `true` in the changelog configuration file (so that bundle files are self-contained) in order to hide the private links. The bundle's changelog entries are sanitized but the individual changelog files are unchanged. ::: -If you are working in a private repo and do not want any pull request or issue links to appear (even if they target a public repo), you can also configure link visibiblity in the [changelog directive](/syntax/changelog.md#hide-links) and [changelog render](/cli/changelog/render.md) command. +If you are working in a private repo and do not want any pull request or issue links to appear (even if they target a public repo), you can also configure link visibility in the [changelog directive](/syntax/changelog.md#hide-links) and [changelog render](/cli/changelog/render.md) command. ## Next steps From 056eecf491de2d98da56ca06b87e23844f047326 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 5 May 2026 16:46:40 -0700 Subject: [PATCH 6/6] Fix formatting in add.md --- docs/cli/changelog/add.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cli/changelog/add.md b/docs/cli/changelog/add.md index 1f3c18ba1..f38a9eaf3 100644 --- a/docs/cli/changelog/add.md +++ b/docs/cli/changelog/add.md @@ -88,6 +88,7 @@ docs-builder changelog add [options...] [-h|--help] : Mutually exclusive with `--prs`, `--issues`, and `--release-version`. : For a plain newline-delimited list of fully-qualified PR URLs, use `--prs` with a file path instead of `--report`. : When the value is an `https://` URL, only hosts allowed by the parser (such as `github.com` and `buildkite.com`) are supported, and the CLI needs network access to fetch the report. + `--release-version ` : Optional: GitHub release tag to use as a source of pull requests (for example, `"v9.2.0"` or `"latest"`). : When specified, the command fetches the release from GitHub, parses PR references from the release notes, and creates one changelog file per PR — without creating a bundle. Only automated GitHub release notes (the default format or [Release Drafter](https://github.com/release-drafter/release-drafter) format) are supported at this time.