Skip to content

Changelog profile parity - final phases #2808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lcawl wants to merge 2 commits into
base: profile-parity
Choose a base branch
from
Draft

Changelog profile parity - final phases #2808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ef069e
Implement Phases 3–5: URL list files, --report option, stricter valid…
lcawl Feb 27, 2026
7f2e49d
Fix path resolution and improve docs
lcawl Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 75 additions & 32 deletions docs/cli/release/changelog-bundle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,20 +28,29 @@ These arguments apply to profile-based bundling:
`[0] <string?>`
: Profile name from `bundle.profiles` in the changelog configuration file.
: For example, "elasticsearch-release".
: When it's specified, the second argument is the version or promotion report URL.
: When specified, the second argument is the version, promotion report URL, or URL list file.

`[1] <string?>`
: Version number or promotion report URL or path.
: For example, "9.2.0" or `https://buildkite.../promotion-report.html`.
: 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`.

`[2] <string?>`
: Optional: Promotion report URL/path or URL list file when the second argument is a version string.
: When provided, `[1]` must be a version string and `[2]` is the PR/issue filter source.
: For example, `docs-builder changelog bundle serverless-release 2026-02 ./promotion-report.html`.

:::{note}
Only the profile-based method currently supports buildkite promotion reports.
There is no equivalent command option.
The third argument (`[2]`) is required when your profile uses `{version}` placeholders in `output` or `output_products` patterns and you also want to filter by a promotion report or URL list. Without it, the version defaults to `"unknown"`.
:::

<!--
TBD: Does the promotion report need to have a specific format? Can we provide more details or an example?
-->
### Profile argument types

The second argument (`[1]`) and optional third argument (`[2]`) accept the following:

- **Version string** — Used for `{version}` substitution in profile patterns. For example, `9.2.0` or `2026-02`.
- **Promotion report URL** — A URL to an HTML promotion report. PR URLs are extracted from it.
- **Promotion report file** — A path to a local `.html` file containing a promotion report.
- **URL list file** — A path to a plain-text file containing one fully-qualified GitHub PR or issue URL per line. For example, `https://github.com/elastic/elasticsearch/pull/123`. The file must contain only PR URLs or only issue URLs, not a mix. Bare numbers and short forms such as `owner/repo#123` are not allowed.

## Options

Expand All @@ -58,7 +67,7 @@ Using any of them with a profile returns an error.

`--directory <string?>`
: Optional: The directory that contains the changelog YAML files.
: When not specified, uses `bundle.directory` from the changelog configuration if set, otherwise the current directory.
: When not specified, falls back to `bundle.directory` from the changelog configuration, then the current working directory. See [Output files](#output-files) for the full resolution order.

`--hide-features <string[]?>`
: Optional: A list of feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs.
Expand All @@ -79,19 +88,18 @@ Using any of them with a profile returns an error.
- `"* * *"` - match all changelogs (equivalent to `--all`)

`--issues <string[]?>`
: Filter by issue URLs or numbers (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers. Can be specified multiple times.
: Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
: 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 specifying issues directly, provide comma-separated values.
: When specifying a file path, provide a single value that points to a newline-delimited file.
: Filter by issue URLs (comma-separated), or a path to a newline-delimited file. Can be specified multiple times.
: Only one filter option can be specified: `--all`, `--input-products`, `--prs`, `--issues`, or `--report`.
: When specifying inline values, comma-separated issue numbers are allowed when `--owner` and `--repo` are also provided.
: 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.

`--no-resolve`
: Optional: Explicitly turn off the `resolve` option if it's specified in the changelog configuration file.

`--output <string?>`
: Optional: The output path for the bundle.
: Can be either (1) a directory path, in which case `changelog-bundle.yaml` is created in that directory, or (2) a file path ending in `.yml` or `.yaml`.
: When not specified, uses `bundle.output_directory` from the changelog configuration (creating `changelog-bundle.yaml` in that directory) if set, otherwise `changelog-bundle.yaml` in the input directory.
: When not specified, falls back to `bundle.output_directory` from the changelog configuration, then the input directory (which is itself resolved from `--directory`, `bundle.directory`, or the current working directory). See [Output files](#output-files) for the full resolution order.

`--output-products <List<ProductInfo>?>`
: Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...".
Expand All @@ -102,11 +110,15 @@ Using any of them with a profile returns an error.
: Falls back to `bundle.owner` in `changelog.yml` when not specified.

`--prs <string[]?>`
: Filter by pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times.
: Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
: 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 specifying PRs directly, provide comma-separated values.
: When specifying a file path, provide a single value that points to a newline-delimited file.
: Filter by pull request URLs (comma-separated), or a path to a newline-delimited file. Can be specified multiple times.
: Only one filter option can be specified: `--all`, `--input-products`, `--prs`, `--issues`, or `--report`.
: When specifying inline values, comma-separated PR numbers are allowed when `--owner` and `--repo` are also provided.
: 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.

`--report <string?>`
: Filter by pull requests extracted from a promotion report. Accepts a URL or a local file path.
: Only one filter option can be specified: `--all`, `--input-products`, `--prs`, `--issues`, or `--report`.
: The report can be an HTML page from Buildkite or any file containing GitHub PR URLs.

`--repo <string?>`
: Optional: The GitHub repository name, required when pull requests or issues are specified as numbers.
Expand All @@ -119,13 +131,30 @@ Using any of them with a profile returns an error.

## Output files

Profile-based bundles are created in `bundle.output_directory`.
If `output_directory` is not set, they are created in the `bundle.directory` alongside the changelog files.
Bundle names are determined by the `bundle.profiles.<name>.output` setting, which can optionally include additional profile-specific paths. For example: `"stack/kibana-{version}.yaml"`.
If that setting is absent, the default name is `changelog-bundle.yaml`
Both modes use the same ordered fallback to determine where to write the bundle. The first value that is set wins:

**Output directory** (where the bundle file is placed):

| Priority | Profile-based | Option-based |
|----------|---------------|--------------|
| 1 | — | `--output` (explicit file or directory path) |
| 2 | `bundle.output_directory` in `changelog.yml` | `bundle.output_directory` in `changelog.yml` |
| 3 | `bundle.directory` in `changelog.yml` | `--directory` CLI option |
| 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.<name>.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"`.

In the option-based mode, when you do not specify `--output`, the command uses `bundle.output_directory` or defaults to the input directory.
When you specify `--output`, it supports two formats:
In option-based mode, when you specify `--output`, it supports two formats:

1. **Directory path**: If you specify a directory path (without a filename), the command creates `changelog-bundle.yaml` in that directory:

Expand All @@ -143,6 +172,11 @@ When you specify `--output`, it supports two formats:

If you specify a file path with a different extension (not `.yml` or `.yaml`), the command returns an error.

:::{note}
"Current working directory" means the directory you are in when you run the command (`pwd`).
Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is recommended so you don't need to rely on running the command from a specific directory.
:::

## 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.
Expand Down Expand Up @@ -280,12 +314,21 @@ docs-builder changelog bundle elasticsearch-release 9.2.0

# Bundle changelogs with partial dates
docs-builder changelog bundle serverless-monthly 2026-02
```

<!--
TO-DO: Add a promotion report example once it works with output_products
```
# Bundle changelogs that match a list of PRs in a downloaded promotion report
docs-builder changelog bundle serverless-release-report 2026-02 ./promotion-report.html
# (version used for {version} substitution; report used as PR filter)
docs-builder changelog bundle serverless-monthly 2026-02 ./promotion-report.html

# Same using a URL list file instead of an HTML promotion report
docs-builder changelog bundle serverless-monthly 2026-02 ./prs.txt
```

For option-based mode, 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
```
-->
83 changes: 71 additions & 12 deletions docs/cli/release/changelog-remove.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,18 @@ These arguments apply to profile-based removal:
`[0] <string?>`
: Profile name from `bundle.profiles` in the changelog configuration file.
: For example, "elasticsearch-release".
: When specified, the second argument is the version or promotion report URL.
: Mutually exclusive with `--all`, `--products`, `--prs`, `--issues`, `--owner`, `--repo`, `--config`, `--directory`, and `--bundles-dir`.
: When specified, the second argument is the version, promotion report URL, or URL list file.
: Mutually exclusive with `--all`, `--products`, `--prs`, `--issues`, `--report`, `--owner`, `--repo`, `--config`, `--directory`, and `--bundles-dir`.

`[1] <string?>`
: Version number or promotion report URL or path.
: For example, "9.2.0" or "https://buildkite.../promotion-report.html".
: 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.

`[2] <string?>`
: Optional: Promotion report URL/path or URL list file when the second argument is a version string.
: When provided, `[1]` must be a version string and `[2]` is the PR/issue filter source.
: For example, `docs-builder changelog remove serverless-release 2026-02 ./promotion-report.html`.

## Options

Expand All @@ -42,8 +48,8 @@ These arguments apply to profile-based removal:

`--bundles-dir <string?>`
: Optional: Override the directory scanned for bundles during the dependency check.
: When not specified, the directory is discovered automatically from config or fallback paths.
: Not allowed with a profile argument. In profile mode, the bundles directory is derived from `bundle.output_directory` in the changelog configuration.
: When not specified, the directory is resolved in order: `bundle.output_directory` from the changelog configuration, then `{changelog-dir}/bundles`, then `{changelog-dir}/../bundles`.
: Not allowed with a profile argument. In profile mode, the same automatic discovery applies.

`--config <string?>`
: Optional: Path to the changelog configuration file.
Expand All @@ -52,8 +58,8 @@ These arguments apply to profile-based removal:

`--directory <string?>`
: Optional: The directory that contains the changelog YAML files.
: When not specified, uses `bundle.directory` from the changelog configuration if set, otherwise the current directory.
: Not allowed with a profile argument. In profile mode, the directory is derived from `bundle.directory` in the changelog configuration.
: When not specified, falls back to `bundle.directory` from the changelog configuration, then the current working directory.
: Not allowed with a profile argument. In profile mode, the same fallback applies (starting from `bundle.directory`).

`--dry-run`
: Print the files that would be removed and any bundle dependency conflicts, without deleting anything.
Expand All @@ -65,9 +71,10 @@ These arguments apply to profile-based removal:
: Valid in both profile and option-based mode.

`--issues <string[]?>`
: Filter by issue URLs or numbers (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers.
: Filter by issue URLs (comma-separated), or a path to a newline-delimited file.
: Can be specified multiple times.
: Exactly one filter option must be specified: `--all`, `--products`, `--prs`, or `--issues`.
: Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, or `--report`.
: When using a file, every line must be a fully-qualified GitHub issue URL. Bare numbers and short forms are not allowed in files.
: Not allowed with a profile argument.

`--owner <string?>`
Expand All @@ -87,15 +94,47 @@ These arguments apply to profile-based removal:
- `"* * *"` — all changelogs (equivalent to `--all`)

`--prs <string[]?>`
: Filter by pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers.
: Filter by pull request URLs (comma-separated), or a path to a newline-delimited file.
: Can be specified multiple times.
: Exactly one filter option must be specified: `--all`, `--products`, `--prs`, or `--issues`.
: Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, or `--report`.
: When using a file, every line must be a fully-qualified GitHub PR URL. Bare numbers and short forms are not allowed in files.
: Not allowed with a profile argument.

`--repo <string?>`
: The GitHub repository name, which is required when pull requests or issues are specified as numbers.
: Not allowed with a profile argument.

`--report <string?>`
: Filter by pull requests extracted from a promotion report. Accepts a URL or a local file path.
: Exactly one filter option must be specified: `--all`, `--products`, `--prs`, `--issues`, or `--report`.
: Not allowed with a profile argument.

## Directory resolution [changelog-remove-dirs]

Both modes use the same ordered fallback to locate changelog YAML files and existing bundles.

**Changelog files directory** (where changelog YAML files are read from):

| 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 |

**Bundles directory** (scanned for existing bundles during the dependency check):

| Priority | Both modes |
|----------|------------|
| 1 | `--bundles-dir` CLI option (option-based only) |
| 2 | `bundle.output_directory` in `changelog.yml` |
| 3 | `{changelog-dir}/bundles` |
| 4 | `{changelog-dir}/../bundles` |

:::{note}
"Current working directory" means the directory you are in when you run the command (`pwd`).
Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is recommended so you don't need to rely on running the command from a specific directory.
:::

## Profile-based removal [changelog-remove-profile]

When a `changelog.yml` configuration file defines `bundle.profiles`, you can use those same profiles with `changelog remove` to remove exactly the changelogs that would be included in a matching bundle.
Expand Down Expand Up @@ -127,3 +166,23 @@ You can also pass a promotion report URL or file path as the second argument, in
```sh
docs-builder changelog remove elasticsearch-release https://buildkite.../promotion-report.html
```

When using a profile with `{version}` in the `output` or `output_products` pattern, pass the version as the second argument and the report as the third:

```sh
docs-builder changelog remove serverless-release 2026-02 ./promotion-report.html
```

Or with a URL list file:

```sh
docs-builder changelog remove serverless-release 2026-02 ./prs.txt
```

For option-based removal with a promotion report:

```sh
docs-builder changelog remove \
--report https://buildkite.../promotion-report.html \
--directory ./docs/changelog
```
Loading
Loading