From 3905cb26075e163bfbc2a3cdc95c42f2fdfd4876 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 27 Mar 2026 18:09:18 -0700 Subject: [PATCH 1/6] [DOCS] Add profile example for --all bundle --- docs/cli/release/changelog-bundle.md | 39 ++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/docs/cli/release/changelog-bundle.md b/docs/cli/release/changelog-bundle.md index 482cd9db4..bf1c0201c 100644 --- a/docs/cli/release/changelog-bundle.md +++ b/docs/cli/release/changelog-bundle.md @@ -372,6 +372,7 @@ If you're using profile-based commands, they're affected by the following fields `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}"` @@ -452,35 +453,46 @@ For example: ```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}-* *" <2> + 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" <3> + products: "elasticsearch {version} ga" <4> output: "elasticsearch-{version}.yaml" # Infer the lifecycle from the version elasticsearch-release: - hide_features: <4> + hide_features: <5> - feature-flag-1 - feature-flag-2 - products: "elasticsearch {version} {lifecycle}" <5> + 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. Bundles 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. -3. Bundles any changelogs that have `product: elasticsearch`, `lifecycle: ga`, and the version specified in the command. -4. Adds a `hide-features` array in the bundle. This is equivalent to the `--hide-features` command option. -5. 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`). +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. @@ -488,6 +500,17 @@ bundle: 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. From ee69eeb9ee9a6442d337acb0cdd31a1e7ec2a69c Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 30 Mar 2026 18:11:28 -0700 Subject: [PATCH 2/6] Move changelog cli files from release folder --- docs/_docset.yml | 18 +++++++-------- docs/_redirects.yml | 8 +++++++ .../changelog-add.md => changelog/add.md} | 0 .../bundle-amend.md} | 2 +- .../bundle.md} | 2 +- .../evaluate-pr.md} | 0 .../gh-release.md} | 2 +- docs/cli/changelog/index.md | 15 +++++++++++++ .../changelog-init.md => changelog/init.md} | 0 .../remove.md} | 10 ++++----- .../render.md} | 2 +- docs/cli/index.md | 2 +- docs/cli/release/index.md | 15 ------------- docs/contribute/changelog.md | 22 +++++++++---------- docs/syntax/changelog.md | 16 +++++++------- 15 files changed, 61 insertions(+), 53 deletions(-) rename docs/cli/{release/changelog-add.md => changelog/add.md} (100%) rename docs/cli/{release/changelog-bundle-amend.md => changelog/bundle-amend.md} (98%) rename docs/cli/{release/changelog-bundle.md => changelog/bundle.md} (99%) rename docs/cli/{release/changelog-evaluate-pr.md => changelog/evaluate-pr.md} (100%) rename docs/cli/{release/changelog-gh-release.md => changelog/gh-release.md} (97%) create mode 100644 docs/cli/changelog/index.md rename docs/cli/{release/changelog-init.md => changelog/init.md} (100%) rename docs/cli/{release/changelog-remove.md => changelog/remove.md} (95%) rename docs/cli/{release/changelog-render.md => changelog/render.md} (98%) delete mode 100644 docs/cli/release/index.md diff --git a/docs/_docset.yml b/docs/_docset.yml index c4404e489..51e6514e5 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -185,17 +185,17 @@ toc: - file: inbound-links-validate.md - file: inbound-links-validate-all.md - file: inbound-links-validate-link-reference.md - - folder: release + - folder: changelog children: - file: index.md - - file: changelog-add.md - - file: changelog-bundle.md - - file: changelog-bundle-amend.md - - file: changelog-evaluate-pr.md - - file: changelog-gh-release.md - - file: changelog-init.md - - file: changelog-remove.md - - file: changelog-render.md + - file: add.md + - file: bundle.md + - file: bundle-amend.md + - file: evaluate-pr.md + - file: gh-release.md + - file: init.md + - file: remove.md + - file: render.md - folder: mcp children: - file: index.md diff --git a/docs/_redirects.yml b/docs/_redirects.yml index da0e6e190..712228159 100644 --- a/docs/_redirects.yml +++ b/docs/_redirects.yml @@ -2,8 +2,16 @@ redirects: 'migration/freeze/gh-action.md' : 'index.md' 'migration/freeze/index.md' : 'index.md' 'cli/mcp.md': 'index.md' + 'cli/release/changelog-add.md': 'cli/changelog/add.md' 'cli/release/changelog-evaluate-artifact.md': 'index.md' + 'cli/release/changelog-evaluate-pr.md': 'cli/changelog/evaluate-pr.md' + 'cli/release/changelog-bundle.md': 'cli/changelog/bundle.md' + 'cli/release/changelog-bundle-amend.md': 'cli/changelog/bundle-amend.md' + 'cli/release/changelog-gh-release.md': 'cli/changelog/gh-release.md' + 'cli/release/changelog-init.md': 'cli/changelog/init.md' 'cli/release/changelog-prepare-artifact.md': 'index.md' + 'cli/release/changelog-remove.md': 'cli/changelog/remove.md' + 'cli/release/changelog-render.md': 'cli/changelog/render.md' 'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md' 'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md' 'testing/redirects/6th-page.md': diff --git a/docs/cli/release/changelog-add.md b/docs/cli/changelog/add.md similarity index 100% rename from docs/cli/release/changelog-add.md rename to docs/cli/changelog/add.md diff --git a/docs/cli/release/changelog-bundle-amend.md b/docs/cli/changelog/bundle-amend.md similarity index 98% rename from docs/cli/release/changelog-bundle-amend.md rename to docs/cli/changelog/bundle-amend.md index 8949eb0a9..f32c740e0 100644 --- a/docs/cli/release/changelog-bundle-amend.md +++ b/docs/cli/changelog/bundle-amend.md @@ -3,7 +3,7 @@ Amend a bundle with additional changelog entries. Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number. -To create a bundle, use [](/cli/release/changelog-bundle.md). +To create a bundle, use [](/cli/changelog/bundle.md). For details and examples, go to [](/contribute/changelog.md). ## Usage diff --git a/docs/cli/release/changelog-bundle.md b/docs/cli/changelog/bundle.md similarity index 99% rename from docs/cli/release/changelog-bundle.md rename to docs/cli/changelog/bundle.md index bf1c0201c..0a1091927 100644 --- a/docs/cli/release/changelog-bundle.md +++ b/docs/cli/changelog/bundle.md @@ -2,7 +2,7 @@ Bundle changelog files. -To create the changelogs, use [](/cli/release/changelog-add.md). +To create the changelogs, use [](/cli/changelog/add.md). For details and examples, go to [](/contribute/changelog.md). ## Usage diff --git a/docs/cli/release/changelog-evaluate-pr.md b/docs/cli/changelog/evaluate-pr.md similarity index 100% rename from docs/cli/release/changelog-evaluate-pr.md rename to docs/cli/changelog/evaluate-pr.md diff --git a/docs/cli/release/changelog-gh-release.md b/docs/cli/changelog/gh-release.md similarity index 97% rename from docs/cli/release/changelog-gh-release.md rename to docs/cli/changelog/gh-release.md index bf0950c91..d89984f77 100644 --- a/docs/cli/release/changelog-gh-release.md +++ b/docs/cli/changelog/gh-release.md @@ -55,7 +55,7 @@ The product, target version, and lifecycle are inferred automatically from the r The `rules.bundle` section of your `changelog.yml` applies to bundles created by this command (after changelog files are gathered from the release). Which fields take effect depends on [bundle rule modes](/contribute/changelog.md#bundle-rule-modes). -For details, refer to [Rules for filtered bundles](/cli/release/changelog-bundle.md#changelog-bundle-rules). +For details, refer to [Rules for filtered bundles](/cli/changelog/bundle.md#changelog-bundle-rules). If you use per-product rule overrides, refer to [Single-product rule resolution (Mode 3 only)](/contribute/changelog.md#changelog-bundle-rule-resolution). ## Examples diff --git a/docs/cli/changelog/index.md b/docs/cli/changelog/index.md new file mode 100644 index 000000000..7efbfc40f --- /dev/null +++ b/docs/cli/changelog/index.md @@ -0,0 +1,15 @@ +--- +navigation_title: "changelog" +--- + +# Changelog commands + +These commands are associated with product release documentation. + +- [changelog add](add.md) - Create a changelog file +- [changelog bundle](bundle.md) - Create a changelog bundle file +- [changelog gh-release](gh-release.md) - Create changelogs and a bundle from a GitHub release +- [changelog init](init.md) - Initialize changelog configuration and folder structure +- [changelog bundle-amend](bundle-amend.md) - Add entries to an existing bundle +- [changelog render](render.md) - Generate markdown output from changelog bundle files +- [changelog evaluate-pr](evaluate-pr.md) - (CI) Evaluate a PR for changelog generation eligibility diff --git a/docs/cli/release/changelog-init.md b/docs/cli/changelog/init.md similarity index 100% rename from docs/cli/release/changelog-init.md rename to docs/cli/changelog/init.md diff --git a/docs/cli/release/changelog-remove.md b/docs/cli/changelog/remove.md similarity index 95% rename from docs/cli/release/changelog-remove.md rename to docs/cli/changelog/remove.md index 8972e2fe3..77a58fd40 100644 --- a/docs/cli/release/changelog-remove.md +++ b/docs/cli/changelog/remove.md @@ -4,7 +4,7 @@ Remove changelog YAML files from a directory. You can use either profile-based or command-option-based removal: -- **Profile-based**: `docs-builder changelog remove ` — uses the same `bundle.profiles` configuration as [`changelog bundle`](/cli/release/changelog-bundle.md) to determine which changelogs to remove. +- **Profile-based**: `docs-builder changelog remove ` — uses the same `bundle.profiles` configuration as [`changelog bundle`](/cli/changelog/bundle.md) to determine which changelogs to remove. - **Option-based**: `docs-builder changelog remove --products "..." ` (or `--prs`, `--issues`, `--all`, `--release-version`, `--report`) — specify the filter directly. These modes are mutually exclusive. You can't combine a profile argument with the command filter options. @@ -31,7 +31,7 @@ These arguments apply to profile-based removal: `[1] ` : Version number, promotion report URL/path, or URL list file. : For example, `9.2.0`, `https://buildkite.../promotion-report.html`, or `/path/to/prs.txt`. -: See [Profile argument types](/cli/release/changelog-bundle.md#profile-argument-types) for details on accepted formats. +: See [Profile argument types](/cli/changelog/bundle.md#profile-argument-types) for details on accepted formats. `[2] ` : Optional: Promotion report URL/path or URL list file when the second argument is a version string. @@ -150,7 +150,7 @@ You can use `--release-version` to fetch pull request references directly from G Only automated GitHub release notes (the default format or [Release Drafter](https://github.com/release-drafter/release-drafter) format) are supported at this time. ::: -This mirrors the equivalent [`--release-version` option on `changelog bundle`](/cli/release/changelog-bundle.md#changelog-bundle-release-version) and is useful when cleaning up after a release-based bundle. +This mirrors the equivalent [`--release-version` option on `changelog bundle`](/cli/changelog/bundle.md#changelog-bundle-release-version) and is useful when cleaning up after a release-based bundle. For example: ```sh @@ -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/release/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 [Lifecycle inference for standard profiles](/cli/changelog/bundle.md#changelog-bundle-standard-profile-lifecycle) 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/release/changelog-bundle.md#changelog-bundle-profile-config). +For the full list of profile configuration fields, go to [Profile configuration fields](/cli/changelog/bundle.md#changelog-bundle-profile-config). diff --git a/docs/cli/release/changelog-render.md b/docs/cli/changelog/render.md similarity index 98% rename from docs/cli/release/changelog-render.md rename to docs/cli/changelog/render.md index 54df08f96..b85b55d4c 100644 --- a/docs/cli/release/changelog-render.md +++ b/docs/cli/changelog/render.md @@ -2,7 +2,7 @@ Generate markdown or asciidoc files from changelog bundle files. -To create the bundle files, use [](/cli/release/changelog-bundle.md). +To create the bundle files, use [](/cli/changelog/bundle.md). For details and examples, go to [](/contribute/changelog.md). ## Usage diff --git a/docs/cli/index.md b/docs/cli/index.md index 044b19b21..55f5242de 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -51,4 +51,4 @@ Assembler builds bring together all isolated documentation set builds and turn t Commands that pertain to creating and publishing product release documentation. -[See available CLI commands for release docs](release/index.md) +[See available CLI commands for release docs](changelog/index.md) diff --git a/docs/cli/release/index.md b/docs/cli/release/index.md deleted file mode 100644 index 4cb846909..000000000 --- a/docs/cli/release/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -navigation_title: "changelog" ---- - -# Changelog commands - -These commands are associated with product release documentation. - -- [changelog add](changelog-add.md) - Create a changelog file -- [changelog bundle](changelog-bundle.md) - Create a changelog bundle file -- [changelog gh-release](changelog-gh-release.md) - Create changelogs and a bundle from a GitHub release -- [changelog init](changelog-init.md) - Initialize changelog configuration and folder structure -- [changelog bundle-amend](changelog-bundle-amend.md) - Add entries to an existing bundle -- [changelog render](changelog-render.md) - Generate markdown output from changelog bundle files -- [changelog evaluate-pr](changelog-evaluate-pr.md) - (CI) Evaluate a PR for changelog generation eligibility diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md index f34fa5f9b..e2f21667f 100644 --- a/docs/contribute/changelog.md +++ b/docs/contribute/changelog.md @@ -24,7 +24,7 @@ To use the `docs-builder changelog` commands in your development workflow: 1. Optional: Add labels to your GitHub pull requests to indicate that they are not notable and should not generate changelogs. For example, `non-issue` or `release_notes:skip`. Alternatively, you can assume that all PRs are *not* notable unless a specific label is present (for example, `@Public`). 1. [Configure changelog settings](#changelog-settings) to correctly interpret your PR labels. 1. [Create changelogs](#changelog-add) with the `docs-builder changelog add` command. - - 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/release/changelog-gh-release.md). + - 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). 1. [Create changelog bundles](#changelog-bundle) with the `docs-builder changelog bundle` command. For example, create a bundle for the pull requests that are included in a product release. 1. [Create documentation](#render-changelogs) with the `docs-builder changelog render` command. @@ -363,7 +363,7 @@ Ideally this task will be automated such that it's performed by a bot or GitHub If you run it from the command line, you must precede any special characters (such as backquotes) with a backslash escape character (`\`). ::: -For up-to-date command usage information, use the `-h` option or refer to [](/cli/release/changelog-add.md). +For up-to-date command usage information, use the `-h` option or refer to [](/cli/changelog/add.md). ### Authorization @@ -506,7 +506,7 @@ docs-builder changelog add \ --strip-title-prefix ``` -In this case, the changelog file derives the title, type, areas, and products from the pull request. If none of the PR's labels match `pivot.products`, the command falls back to `products.default` or repository name inference from `--repo` (refer to [Products resolution](/cli/release/changelog-add.md#products-resolution) for more details). +In this case, the changelog file derives the title, type, areas, and products from the pull request. If none of the PR's labels match `pivot.products`, the command falls back to `products.default` or repository name inference from `--repo` (refer to [Products resolution](/cli/changelog/add.md#products-resolution) for more details). The command also looks for patterns like `Fixes #123`, `Closes owner/repo#456`, `Resolves https://github.com/.../issues/789` in the pull request to derive its issues. Similarly, when using `--issues`, the command extracts linked PRs from the issue body (for example, "Fixed by #123"). You can turn off this behavior in either case with the `--no-extract-issues` flag or by setting `extract.issues: false` in the changelog configuration file. The `extract.issues` setting applies to both directions: issues extracted from PR bodies (when using `--prs`) and PRs extracted from issue bodies (when using `--issues`). The `--strip-title-prefix` option in this example means that if the PR title has a prefix in square brackets (such as `[ES|QL]` or `[Security]`), it is automatically removed from the changelog title. Multiple square bracket prefixes are also supported (for example `[Discover][ESQL] Title` becomes `Title`). If a colon follows the closing bracket, it is also removed. @@ -629,7 +629,7 @@ 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/release/changelog-gh-release.md) +The command parses the release notes, creates one changelog file per pull request found, and creates a `changelog-bundle.yaml` file — all in a single step. Refer to [](/cli/changelog/gh-release.md) :::{note} This command requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API. Refer to [Authorization](#authorization) for details. @@ -640,7 +640,7 @@ This command requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an 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/release/changelog-bundle.md). +For up-to-date details, use the `-h` option or refer to [](/cli/changelog/bundle.md). The command supports two mutually exclusive usage modes: @@ -950,7 +950,7 @@ You can also combine multiple `--prs` options: 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/release/changelog-bundle.md). +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: @@ -1001,7 +1001,7 @@ The bundle's product metadata is inferred automatically from the release tag and :::{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/release/changelog-gh-release.md) +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] @@ -1020,7 +1020,7 @@ docs-builder changelog bundle \ The bundle output will include a `hide-features` field: @@ -1068,7 +1068,7 @@ The changelogs from all matching amend files are combined with the parent bundle 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/release/changelog-bundle-amend.md). +For more details and examples, go to [](/cli/changelog/bundle-amend.md). ## Create documentation @@ -1141,7 +1141,7 @@ All product-specific filtering must be configured at bundle time via `rules.bund ### Generate markdown or asciidoc [render-changelogs] The `docs-builder changelog render` command creates markdown or asciidoc files from changelog bundles for documentation purposes. -For up-to-date details, use the `-h` command option or refer to [](/cli/release/changelog-render.md). +For up-to-date details, use the `-h` command option or refer to [](/cli/changelog/render.md). Before you can use this command you must create changelog files and collect them into bundles. For example, the `docs-builder changelog bundle` command creates a file like this: @@ -1335,4 +1335,4 @@ When using a file for `--prs` or `--issues`, every line must be a fully-qualifie docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run ``` -For full option details, go to [](/cli/release/changelog-remove.md). +For full option details, go to [](/cli/changelog/remove.md). diff --git a/docs/syntax/changelog.md b/docs/syntax/changelog.md index be0651a4e..a3086b735 100644 --- a/docs/syntax/changelog.md +++ b/docs/syntax/changelog.md @@ -132,10 +132,10 @@ Reserved for future configuration use. The directive does not currently load or 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/release/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. See the [changelog bundle documentation](/cli/changelog/bundle.md#changelog-bundle-rules) for full syntax. `rules.bundle` supports product, type, and area filtering, and per-product overrides. -For full syntax, refer to the [rules for filtered bundles](/cli/release/changelog-bundle.md#changelog-bundle-rules). +For full syntax, refer to the [rules for filtered bundles](/cli/changelog/bundle.md#changelog-bundle-rules). ## Hiding features @@ -299,12 +299,12 @@ The following renders all changelog bundles from the default `changelog/bundles/ | Generating static markdown files for external use | `changelog render` command | | Selective rendering of specific versions | `changelog render` command | -The `{changelog}` directive is ideal for release notes pages that should always show the complete changelog history. For more selective workflows or external publishing, use the [`changelog render`](../cli/release/changelog-render.md) command. +The `{changelog}` directive is ideal for release notes pages that should always show the complete changelog history. For more selective workflows or external publishing, use the [`changelog render`](/cli/changelog/render.md) command. ## Related -- [Create and bundle changelogs](../contribute/changelog.md) — Learn how to create changelog entries and bundles -- [`changelog add`](../cli/release/changelog-add.md) — CLI command to create changelog entries -- [`changelog bundle`](../cli/release/changelog-bundle.md) — CLI command to bundle changelog entries -- [`changelog remove`](../cli/release/changelog-remove.md) — CLI command to remove changelog files -- [`changelog render`](../cli/release/changelog-render.md) — CLI command to render changelogs to markdown files +- [Create and bundle changelogs](/contribute/changelog.md) — Learn how to create changelog entries and bundles +- [`changelog add`](/cli/changelog/add.md) — CLI command to create changelog entries +- [`changelog bundle`](/cli/changelog/bundle.md) — CLI command to bundle changelog entries +- [`changelog remove`](/cli/changelog/remove.md) — CLI command to remove changelog files +- [`changelog render`](/cli/changelog/render.md) — CLI command to render changelogs to markdown files From da212e76d39c24755bb39dfdb402da2c81a07d75 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 30 Mar 2026 18:16:52 -0700 Subject: [PATCH 3/6] Fix link in render.md --- docs/cli/changelog/render.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/changelog/render.md b/docs/cli/changelog/render.md index b85b55d4c..81c756e27 100644 --- a/docs/cli/changelog/render.md +++ b/docs/cli/changelog/render.md @@ -37,7 +37,7 @@ docs-builder changelog render [options...] [-h|--help] : Paths support tilde (`~`) expansion and relative paths. :::{note} -The `render` command automatically discovers and merges `.amend-*.yaml` files with their parent bundle. For more information about amended bundles, go to [](changelog-bundle-amend.md). +The `render` command automatically discovers and merges `.amend-*.yaml` files with their parent bundle. For more information about amended bundles, go to [](bundle-amend.md). ::: `--file-type ` From b65d08deb265fff8a293b6ed75102b3c93145ae5 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 31 Mar 2026 07:07:36 -0700 Subject: [PATCH 4/6] Redirect for index.md --- docs/_redirects.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_redirects.yml b/docs/_redirects.yml index 712228159..350e9d57b 100644 --- a/docs/_redirects.yml +++ b/docs/_redirects.yml @@ -12,6 +12,7 @@ redirects: 'cli/release/changelog-prepare-artifact.md': 'index.md' 'cli/release/changelog-remove.md': 'cli/changelog/remove.md' 'cli/release/changelog-render.md': 'cli/changelog/render.md' + 'cli/release/index.md': 'cli/changelog/index.md' 'testing/redirects/4th-page.md': 'testing/redirects/5th-page.md' 'testing/redirects/9th-page.md': '!testing/redirects/5th-page.md' 'testing/redirects/6th-page.md': From a06fd7efde358326c5d9cbb697aa4ebfd3e0b61a Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 2 Apr 2026 09:16:33 -0700 Subject: [PATCH 5/6] Update test links --- .../authoring/Generator/LinkReferenceFile.fs | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/tests/authoring/Generator/LinkReferenceFile.fs b/tests/authoring/Generator/LinkReferenceFile.fs index 8b0ae43f5..e5e9b7f1e 100644 --- a/tests/authoring/Generator/LinkReferenceFile.fs +++ b/tests/authoring/Generator/LinkReferenceFile.fs @@ -64,6 +64,15 @@ Through various means $$$including-this-inline-syntax$$$ }, "url_path_prefix": "", "links": { + "cli/changelog/add.md": {}, + "cli/changelog/bundle-amend.md": {}, + "cli/changelog/bundle.md": {}, + "cli/changelog/evaluate-pr.md": {}, + "cli/changelog/gh-release.md": {}, + "cli/changelog/index.md": {}, + "cli/changelog/init.md": {}, + "cli/changelog/remove.md": {}, + "cli/changelog/render.md": {}, "file.md": {}, "index.md": { "anchors": [ @@ -96,12 +105,39 @@ Through various means $$$including-this-inline-syntax$$$ "cli/mcp.md": { "to": "index.md" }, + "cli/release/changelog-add.md": { + "to": "cli/changelog/add.md" + }, "cli/release/changelog-evaluate-artifact.md": { "to": "index.md" }, + "cli/release/changelog-evaluate-pr.md": { + "to": "cli/changelog/evaluate-pr.md" + }, + "cli/release/changelog-bundle.md": { + "to": "cli/changelog/bundle.md" + }, + "cli/release/changelog-bundle-amend.md": { + "to": "cli/changelog/bundle-amend.md" + }, + "cli/release/changelog-gh-release.md": { + "to": "cli/changelog/gh-release.md" + }, + "cli/release/changelog-init.md": { + "to": "cli/changelog/init.md" + }, "cli/release/changelog-prepare-artifact.md": { "to": "index.md" }, + "cli/release/changelog-remove.md": { + "to": "cli/changelog/remove.md" + }, + "cli/release/changelog-render.md": { + "to": "cli/changelog/render.md" + }, + "cli/release/index.md": { + "to": "cli/changelog/index.md" + }, "testing/redirects/4th-page.md": { "to": "testing/redirects/5th-page.md" }, From 518174e56225eb3c8277e5da3a6cf4f27e02e4e5 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 2 Apr 2026 09:34:51 -0700 Subject: [PATCH 6/6] Fix links --- docs/cli/changelog/bundle.md | 2 +- docs/contribute/changelog.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cli/changelog/bundle.md b/docs/cli/changelog/bundle.md index 0a1091927..882e857dc 100644 --- a/docs/cli/changelog/bundle.md +++ b/docs/cli/changelog/bundle.md @@ -141,7 +141,7 @@ The `--input-products` option determines which changelog files are gathered for : By default, the bundle contains only the file names and checksums. `--sanitize-private-links` -: Optional: Turn on [private link sanitization](/cli/release/changelog-bundle.md#private-link-sanitization). +: Optional: Turn on [private link sanitization](#private-link-sanitization). : Pull requests and issues that target repositories marked `private: true` in the `references` section of `assembler.yml` are rewritten as quoted `# PRIVATE:` sentinel strings in the bundle file. : This option requires a resolved bundle: use `--resolve` or set `bundle.resolve: true` in the `changelog.yml`. : If sanitization is enabled and the bundle is not resolved, the command fails. diff --git a/docs/contribute/changelog.md b/docs/contribute/changelog.md index e2f21667f..379bdce82 100644 --- a/docs/contribute/changelog.md +++ b/docs/contribute/changelog.md @@ -714,7 +714,7 @@ Top-level `bundle` fields: | `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 `sanitize_private_links` is enabled. | -| `sanitize_private_links` | When `true`, rewrites PR/issue references that target private repositories (per `assembler.yml` `references`) to quoted `# PRIVATE:` sentinel strings in bundle YAML. Requires `resolve: true` and a non-empty `references` section in `assembler.yml`. Default `false`. Refer to [Private link sanitization at bundle time](/cli/release/changelog-bundle.md#private-link-sanitization). | +| `sanitize_private_links` | When `true`, rewrites PR/issue references that target private repositories (per `assembler.yml` `references`) to quoted `# PRIVATE:` sentinel strings in bundle YAML. Requires `resolve: true` and a non-empty `references` section in `assembler.yml`. Default `false`. Refer to [Private link sanitization at bundle time](/cli/changelog/bundle.md#private-link-sanitization). | Profile configuration fields in `bundle.profiles`: @@ -1048,9 +1048,9 @@ The `--hide-features` option on the `render` command and the `hide-features` fie A changelog can reference multiple pull requests and issues in the `prs` and `issues` array fields. -To comment out the private links in all changelogs in your bundles, refer to [changelog bundle](/cli/release/changelog-bundle.md#private-link-sanitization). +To comment out the private links in all changelogs in your bundles, refer to [changelog bundle](/cli/changelog/bundle.md#private-link-sanitization). -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/release/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. :::{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.