You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
: If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (`\`).
30
30
31
31
`--no-extract-release-notes`
32
-
: Optional: Turn off extraction of release notes from PR descriptions.
33
-
: The extractor looks for content in various formats in the PR description:
32
+
: Optional: Turn off extraction of release notes from PR or issue descriptions.
33
+
: The extractor looks for content in various formats in the PR or issue description:
34
34
: - `Release Notes: ...`
35
35
: - `Release-Notes: ...`
36
36
: - `release notes: ...`
37
37
: - `Release Note: ...`
38
38
: - `Release Notes - ...`
39
39
: - `## Release Note` (as a markdown header)
40
-
: Short release notes (≤120 characters, single line) are used as the changelog title (only if `--title` is not explicitly provided).
41
-
: Long release notes (>120 characters or multi-line) are used as the changelog description (only if `--description` is not explicitly provided).
40
+
: Matched release note text is used as the changelog description (only if `--description` is not explicitly provided). The changelog title is always taken from `--title` or from the PR or issue title, not from the release note section.
42
41
: By default, the behavior is determined by the `extract.release_notes` changelog configuration setting.
Copy file name to clipboardExpand all lines: docs/cli/changelog/bundle.md
+64Lines changed: 64 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -54,6 +54,13 @@ The second argument (`[1]`) and optional third argument (`[2]`) accept the follo
54
54
-**Promotion report file** — A path to a downloaded `.html` file containing a promotion report.
55
55
-**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.
56
56
57
+
## General options
58
+
59
+
These options work with both profile-based and option-based modes.
60
+
61
+
`--plan`
62
+
: Output a structured set of CI step outputs (`needs_network`, `needs_github_token`, `output_path`) describing Docker flags, network requirements, and the resolved output path, then exit without generating the bundle. Intended for CI actions that need to determine container configuration before running the actual bundle step. When running outside GitHub Actions, the output is written to stdout.
63
+
57
64
## Options
58
65
59
66
The following options are only valid in option-based mode (no profile argument).
@@ -71,6 +78,13 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp
71
78
: Optional: The directory that contains the changelog YAML files.
72
79
: 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.
73
80
81
+
`--description <string?>`
82
+
: Optional: Bundle description text with placeholder support.
83
+
: Supports `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` placeholders. Overrides `bundle.description` from config.
84
+
: When using `{version}` or `{lifecycle}` placeholders, predictable substitution values are required:
85
+
: - **Option-based mode**: Requires `--output-products` to be explicitly specified
86
+
: - **Profile-based mode**: Requires either a version argument OR `output_products` in the profile configuration
87
+
74
88
`--hide-features <string[]?>`
75
89
: Optional: A list of feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs.
By default all changelogs that match PRs in the GitHub release notes are included in the bundle.
348
362
To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules).
349
363
364
+
### Bundle with description
365
+
366
+
You can add a description to bundles using the `--description` option. For simple descriptions, use regular quotes:
367
+
368
+
```sh
369
+
docs-builder changelog bundle \
370
+
--all \
371
+
--description "This release includes new features and bug fixes."
372
+
```
373
+
374
+
For multiline descriptions with multiple paragraphs, lists, and links, use ANSI-C quoting (`$'...'`) with `\n` for line breaks:
375
+
376
+
```sh
377
+
docs-builder changelog bundle \
378
+
--all \
379
+
--description $'This release includes significant improvements:\n\n- Enhanced performance\n- Bug fixes and stability improvements\n\nFor security updates, go to [security announcements](https://example.com/docs).'
380
+
```
381
+
382
+
When using placeholders in option-based mode, you must explicitly specify `--output-products` for predictable substitution:
383
+
384
+
```sh
385
+
docs-builder changelog bundle \
386
+
--all \
387
+
--output-products "elasticsearch 9.1.0 ga" \
388
+
--description "Elasticsearch {version} includes performance improvements. Download: https://github.com/{owner}/{repo}/releases/tag/v{version}"
389
+
```
390
+
350
391
## Profile-based examples
351
392
352
393
When the changelog configuration file defines `bundle.profiles`, you can use those profiles with the `changelog bundle` command.
**Placeholder validation**: If your profile uses `{version}` or `{lifecycle}` placeholders in the description, you must ensure predictable substitution values:
481
+
482
+
```sh
483
+
# ✅ Good: Version provided for placeholder substitution
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`.
: Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`.
33
33
34
+
`--description <string?>`
35
+
: Optional: Bundle description text with placeholder support.
36
+
: Supports `{version}`, `{lifecycle}`, `{owner}`, and `{repo}` placeholders. Overrides `bundle.description` from config.
37
+
34
38
`--output <string?>`
35
39
: Optional: Output directory for the generated changelog files. Falls back to `bundle.directory` in `changelog.yml` when not specified. Defaults to `./changelogs`.
Copy file name to clipboardExpand all lines: docs/cli/changelog/init.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,8 @@ If no docs folder exists, the command creates `{path}/docs` and places `changelo
13
13
The command creates a `changelog.yml` configuration file (from the built-in template) and `changelog` and `releases` subdirectories in the `docs` folder.
14
14
When `--changelog-dir` or `--bundles-dir` is specified, the corresponding `bundle.directory` and `bundle.output_directory` values in `changelog.yml` are set or updated (whether creating a new file or the file already exists).
15
15
16
+
When the template is written for the first time, the command can **seed**`bundle.owner`, `bundle.repo`, and `bundle.link_allow_repos` so PR and issue links resolve under the explicit link allowlist in [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) (there is no implicit allow for your own repository). Seeding runs when `git` remote `origin` points at **github.com** and/or when you pass `--owner` and/or `--repo`. CLI values override values inferred from `git`. If you pass `--repo` without `--owner` and `git` does not supply an owner, the owner defaults to `elastic`. If neither `git` nor CLI provides enough information, the placeholder line is removed from the template and you can set bundle fields manually.
: Optional: GitHub organization or user for `bundle.owner` and for seeding `bundle.link_allow_repos` when creating `changelog.yml`. Overrides the owner parsed from `git` remote `origin`.
40
+
41
+
`--repo <string?>`
42
+
: Optional: GitHub repository name for `bundle.repo` and for seeding `bundle.link_allow_repos` when creating `changelog.yml`. Overrides the repository name parsed from `git` remote `origin`.
43
+
36
44
## Examples
37
45
38
46
Initialize changelog (creates or uses docs folder, places `changelog.yml` there, plus `changelog` and `releases` subdirectories):
@@ -55,3 +63,9 @@ docs-builder changelog init \
55
63
--changelog-dir ./my-changelogs \
56
64
--bundles-dir ./my-releases
57
65
```
66
+
67
+
Initialize without relying on `git` (for example in a clean checkout or CI), setting the GitHub owner and repository used to seed bundle defaults and `link_allow_repos`:
0 commit comments