Changelog profile parity - final phases (#2808)

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Co-authored-by: Felipe Cotti <felipe.cotti@elastic.co>

Author: 3 people

docs/cli/release/changelog-add.md

@@ -110,14 +110,10 @@ docs-builder changelog add [options...] [-h|--help]
 :   The valid types are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
 
 `--use-pr-number`
-:   Optional: Use the PR number(s) as the filename instead of generating it from a timestamp and title.
-:   With multiple PRs, uses hyphen-separated numbers (for example, `137431-137432.yaml`).
-:   Requires `--prs`. Mutually exclusive with `--use-issue-number`.
+:   Optional: Use PR numbers for filenames instead of timestamp-slug. With both `--prs` (which creates one changelog per specified PR) and `--issues` (which creates one changelog per specified issue), each changelog filename will be derived from its PR numbers. Requires `--prs` or `--issues`. Mutually exclusive with `--use-issue-number`.
 
 `--use-issue-number`
-:   Optional: Use the issue number(s) as the filename instead of generating it from a timestamp and title.
-:   With multiple issues, uses hyphen-separated numbers (for example, `12345-12346.yaml`).
-:   Requires `--issues`. When both `--issues` and `--prs` are specified, still uses the issue number for the filename if this flag is set. Mutually exclusive with `--use-pr-number`.
+:   Optional: Use issue numbers for filenames instead of timestamp-slug. With both `--prs` (which creates one changelog per specified PR) and `--issues` (which creates one changelog per specified issue), each changelog filename will be derived from its issues. Requires `--prs` or `--issues`. Mutually exclusive with `--use-pr-number`.
 
 :::{important}
 `--use-pr-number` and `--use-issue-number` are mutually exclusive; specify only one.

docs/cli/release/changelog-bundle.md

@@ -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
 
@@ -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.
@@ -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.
@@ -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?>`
@@ -87,23 +94,53 @@ 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.
 
 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.
 
-Only the `products` field from a profile is used for removal. The `output`, `output_products`, `repo`, `owner`, and `hide_features` fields are bundle-specific and are ignored.
-
 For example, if your configuration file defines:
 
 ```yaml
@@ -122,8 +159,22 @@ 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.
 
-You can also pass a promotion report URL or file path as the second argument, in which case the command removes changelogs whose PR URLs appear in the report:
+:::{note}
+The `output_products`, `repo`, `owner`, and `hide_features` fields are not relevant to changelog removal and are ignored.
+:::
+
+You can also pass a promotion report URL or file path, in which case the command removes changelogs that have `prs` that match the report.
+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 elasticsearch-release https://buildkite.../promotion-report.html
+docs-builder changelog remove serverless-report ./prs.txt
 ```