Skip to content

Commit 0b29cc8

Browse files
lcawllcawl
authored
Add tips about escape characters in changelog docs (#2670)
1 parent 7e7ab39 commit 0b29cc8

3 files changed

Lines changed: 63 additions & 111 deletions

File tree

‎docs/cli/release/changelog-add.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ docs-builder changelog add [options...] [-h|--help]
1313

1414
`--action <string?>`
1515
: Optional: What users must do to mitigate.
16+
: If the content contains any special characters such as backquotes(`), you must precede it with a backslash escape character (`\`).
1617

1718
`--areas <string[]?>`
1819
: Optional: Areas affected (comma-separated or specify multiple times).
@@ -22,6 +23,7 @@ docs-builder changelog add [options...] [-h|--help]
2223

2324
`--description <string?>`
2425
: Optional: Additional information about the change (max 600 characters).
26+
: If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (`\`).
2527

2628
`--no-extract-release-notes`
2729
: Optional: Turn off extraction of release notes from PR descriptions.
@@ -43,6 +45,7 @@ docs-builder changelog add [options...] [-h|--help]
4345

4446
`--impact <string?>`
4547
: Optional: How the user's environment is affected.
48+
: If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (`\`).
4649

4750
`--issues <string[]?>`
4851
: Optional: Issue numbers (comma-separated or specify multiple times).
@@ -89,6 +92,7 @@ docs-builder changelog add [options...] [-h|--help]
8992
: A short, user-facing title (max 80 characters)
9093
: Required if `--pr` is not specified.
9194
: If both `--pr` and `--title` are specified, the latter value is used instead of what exists in the PR.
95+
: If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (`\`).
9296

9397
`--type <string>`
9498
: Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).

‎docs/cli/release/changelog-bundle.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,57 @@ These arguments apply to profile-based bundling:
8383
`--resolve`
8484
: Optional: Copy the contents of each changelog file into the entries array.
8585
: By default, the bundle contains only the file names and checksums.
86+
87+
## Output file location
88+
89+
The `--output` option supports two formats:
90+
91+
1. **Directory path**: If you specify a directory path (without a filename), the command creates `changelog-bundle.yaml` in that directory:
92+
93+
```sh
94+
docs-builder changelog bundle --all --output /path/to/output/dir
95+
# Creates /path/to/output/dir/changelog-bundle.yaml
96+
```
97+
98+
2. **File path**: If you specify a file path ending in `.yml` or `.yaml`, the command uses that exact path:
99+
100+
```sh
101+
docs-builder changelog bundle --all --output /path/to/custom-bundle.yaml
102+
# Creates /path/to/custom-bundle.yaml
103+
```
104+
105+
If you specify a file path with a different extension (not `.yml` or `.yaml`), the command returns an error.
106+
107+
## Repository name in bundles [changelog-bundle-repo]
108+
109+
When you specify the `--repo` option, the repository name is stored in the bundle's product metadata.
110+
This ensures that PR and issue links are generated correctly when the bundle is rendered.
111+
112+
```sh
113+
docs-builder changelog bundle \
114+
--input-products "cloud-serverless 2025-12-02 *" \
115+
--repo cloud \ <1>
116+
--output /path/to/bundles/2025-12-02.yaml
117+
```
118+
119+
1. The GitHub repository name. This is stored in each product entry in the bundle.
120+
121+
The bundle output will include a `repo` field in each product:
122+
123+
```yaml
124+
products:
125+
- product: cloud-serverless
126+
target: 2025-12-02
127+
repo: cloud
128+
entries:
129+
- file:
130+
name: 1765495972-new-feature.yaml
131+
checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464
132+
```
133+
134+
When rendering, pull request and issue links will use `https://github.com/elastic/cloud/...` instead of the product ID in the URL.
135+
136+
:::{note}
137+
If the `repo` field is not specified, the product ID is used as a fallback for link generation.
138+
This may result in broken links if the product ID doesn't match the GitHub repository name (for example, `cloud-serverless` vs `cloud`).
139+
:::

‎docs/contribute/changelog.md‎

Lines changed: 5 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -87,36 +87,11 @@ Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/ma
8787
You can use the `docs-builder changelog add` command to create a changelog file.
8888

8989
:::{tip}
90-
Ideally this task will be automated such that it's performed by a bot or GitHub action when you create a pull request. More details to come as we refine the workflows.
90+
Ideally this task will be automated such that it's performed by a bot or GitHub action when you create a pull request.
91+
If you run it from the command line, you must precede any special characters (such as backquotes) with a backslash escape character (`\`).
9192
:::
9293

93-
For up-to-date command usage information, use the `-h` option:
94-
95-
```sh
96-
Add a new changelog from command-line input
97-
98-
Options:
99-
--products <List<ProductArgument>?> Optional: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"). If not specified, will be inferred from repository or config defaults. [Default: null]
100-
--action <string?> Optional: What users must do to mitigate [Default: null]
101-
--areas <string[]?> Optional: Area(s) affected (comma-separated or specify multiple times) [Default: null]
102-
--config <string?> Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' [Default: null]
103-
--description <string?> Optional: Additional information about the change (max 600 characters) [Default: null]
104-
--no-extract-release-notes Optional: Turn off extraction of release notes from PR descriptions. By default, release notes are extracted when using --prs. Short release notes (≤120 characters, single line) are used as the title, long release notes (>120 characters or multi-line) are used as the description.
105-
--no-extract-issues Optional: Turn off extraction of linked issues from PR body (e.g., "Fixes #123"). By default, linked issues are extracted when using --prs.
106-
--feature-id <string?> Optional: Feature flag ID [Default: null]
107-
--highlight <bool?> Optional: Include in release highlights [Default: null]
108-
--impact <string?> Optional: How the user's environment is affected [Default: null]
109-
--issues <string[]?> Optional: Issue URL(s) (comma-separated or specify multiple times) [Default: null]
110-
--owner <string?> Optional: GitHub repository owner (used when --prs contains just numbers) [Default: null]
111-
--output <string?> Optional: Output directory for the changelog. Defaults to current directory [Default: null]
112-
--prs <string[]?> Optional: Pull request URL(s) or PR number(s) (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times. Each occurrence can be either comma-separated PRs (e.g., `--prs "https://github.com/owner/repo/pull/123,6789"`) or a file path (e.g., `--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. If --owner and --repo are provided, PR numbers can be used instead of URLs. If specified, --title can be derived from the PR. If mappings are configured, --areas and --type can also be derived from the PR. Creates one changelog file per PR. [Default: null]
113-
--repo <string?> Optional: GitHub repository name (used when --prs contains just numbers) [Default: null]
114-
--strip-title-prefix Optional: When used with --prs, remove square brackets and text within them from the beginning of PR titles, and also remove a colon if it follows the closing bracket (e.g., "[Inference API] Title" becomes "Title", "[ES|QL]: Title" becomes "Title", "[Discover][ESQL] Title" becomes "Title")
115-
--subtype <string?> Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) [Default: null]
116-
--title <string?> Optional: A short, user-facing title (max 80 characters). Required if --pr is not specified. If --pr and --title are specified, the latter value is used instead of what exists in the PR. [Default: null]
117-
--type <string?> Optional: Type of change (feature, enhancement, bug-fix, breaking-change, etc.). Required if --pr is not specified. If mappings are configured, type can be derived from the PR. [Default: null]
118-
--use-pr-number Optional: Use the PR number as the filename instead of generating it from a unique ID and title
119-
```
94+
For up-to-date command usage information, use the `-h` option or refer to [](/cli/release/changelog-add.md).
12095

12196
### Authorization
12297

@@ -345,23 +320,7 @@ This creates one changelog file for each PR specified, whether from files or dir
345320
## Create bundles [changelog-bundle]
346321

347322
You can use the `docs-builder changelog bundle` command to create a YAML file that lists multiple changelogs.
348-
For up-to-date details, use the `-h` option:
349-
350-
```sh
351-
Bundle changelogs
352-
353-
Options:
354-
--all Include all changelogs in the directory. Only one filter option can be specified: `--all`, `--input-products`, or `--prs`.
355-
--directory <string?> Optional: Directory containing changelog YAML files. Defaults to current directory [Default: null]
356-
--hide-features <string[]?> Optional: Feature IDs to mark as hidden in the bundle output (comma-separated), or a path to a newline-delimited file containing feature IDs. Can be specified multiple times. When the bundle is rendered (by CLI render or {changelog} directive), entries with matching feature-id values will be commented out. [Default: null]
357-
--input-products <List<ProductInfo>?> Filter by products in format "product target lifecycle, ..." (e.g., "cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"). When specified, all three parts (product, target, lifecycle) are required but can be wildcards (*). Examples: "elasticsearch * *" matches all elasticsearch changelogs, "cloud-serverless 2025-12-02 *" matches cloud-serverless 2025-12-02 with any lifecycle, "* 9.3.* *" matches any product with target starting with "9.3.", "* * *" matches all changelogs (equivalent to --all). Only one filter option can be specified: `--all`, `--input-products`, or `--prs`. [Default: null]
358-
--output <string?> Optional: Output path for the bundled changelog. 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. Defaults to 'changelog-bundle.yaml' in the input directory [Default: null]
359-
--output-products <List<ProductInfo>?> Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...". Overrides any values from changelogs. [Default: null]
360-
--owner <string?> GitHub repository owner (required only when PRs are specified as numbers) [Default: null]
361-
--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`, or `--prs`. [Default: null]
362-
--repo <string?> GitHub repository name. When specified, this value is stored in the bundle's product metadata and used to generate correct PR/issue links during rendering. Required when PRs are specified as numbers. [Default: null]
363-
--resolve Optional: Copy the contents of each changelog file into the entries array. By default, the bundle contains only the file names and checksums.
364-
```
323+
For up-to-date details, use the `-h` option or refer to [](/cli/release/changelog-bundle.md).
365324

366325
You can specify only one of the following filter options:
367326

@@ -519,26 +478,6 @@ entries:
519478
When a changelog matches multiple `--input-products` filters, it appears only once in the bundle. This deduplication applies even when using `--all` or `--prs`.
520479
:::
521480

522-
### Output file location
523-
524-
The `--output` option supports two formats:
525-
526-
1. **Directory path**: If you specify a directory path (without a filename), the command creates `changelog-bundle.yaml` in that directory:
527-
528-
```sh
529-
docs-builder changelog bundle --all --output /path/to/output/dir
530-
# Creates /path/to/output/dir/changelog-bundle.yaml
531-
```
532-
533-
2. **File path**: If you specify a file path ending in `.yml` or `.yaml`, the command uses that exact path:
534-
535-
```sh
536-
docs-builder changelog bundle --all --output /path/to/custom-bundle.yaml
537-
# Creates /path/to/custom-bundle.yaml
538-
```
539-
540-
If you specify a file path with a different extension (not `.yml` or `.yaml`), the command returns an error.
541-
542481
### Hide features in bundles [changelog-bundle-hide-features]
543482

544483
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.
@@ -573,38 +512,6 @@ When this bundle is rendered (either via the `changelog render` command or the `
573512
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.
574513
:::
575514

576-
### Repository name in bundles [changelog-bundle-repo]
577-
578-
When you specify the `--repo` option, the repository name is stored in the bundle's product metadata. This ensures that PR and issue links are generated correctly when the bundle is rendered.
579-
580-
```sh
581-
docs-builder changelog bundle \
582-
--input-products "cloud-serverless 2025-12-02 *" \
583-
--repo cloud \ <1>
584-
--output /path/to/bundles/2025-12-02.yaml
585-
```
586-
587-
1. The GitHub repository name. This is stored in each product entry in the bundle.
588-
589-
The bundle output will include a `repo` field in each product:
590-
591-
```yaml
592-
products:
593-
- product: cloud-serverless
594-
target: 2025-12-02
595-
repo: cloud
596-
entries:
597-
- file:
598-
name: 1765495972-new-feature.yaml
599-
checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464
600-
```
601-
602-
When rendering, PR/issue links will use `https://github.com/elastic/cloud/...` instead of the product ID in the URL.
603-
604-
:::{note}
605-
If the `repo` field is not specified, the product ID is used as a fallback for link generation. This may result in broken links if the product ID doesn't match the GitHub repository name (e.g., `cloud-serverless` vs `cloud`).
606-
:::
607-
608515
### Amend bundles [changelog-bundle-amend]
609516

610517
When you need to add entries to an existing bundle without modifying the original file, you can create amend bundles. Amend bundles follow a specific naming convention: `{parent-bundle-name}.amend-{N}.yaml` where `{N}` is a sequence number.
@@ -645,20 +552,7 @@ By default, the directive renders all bundles from `changelog/bundles/` (relativ
645552
### Generate markdown or asciidoc [render-changelogs]
646553

647554
The `docs-builder changelog render` command creates markdown or asciidoc files from changelog bundles for documentation purposes.
648-
For up-to-date details, use the `-h` command option:
649-
650-
```sh
651-
Render bundled changelog(s) to markdown or asciidoc files
652-
653-
Options:
654-
--input <string[]?> Required: Bundle input(s) in format "bundle-file-path|changelog-file-path|repo|link-visibility" (use pipe as delimiter). To merge multiple bundles, separate them with commas. Only bundle-file-path is required. link-visibility can be "hide-links" or "keep-links" (default). Paths must be absolute or use environment variables; tilde (~) expansion is not supported. [Default: null]
655-
--config <string?> Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' [Default: null]
656-
--file-type <string?> Optional: Output file type. Valid values: "markdown" or "asciidoc". Defaults to "markdown" [Default: @"markdown"]
657-
--hide-features <string[]?> Filter by feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs. Can be specified multiple times. Entries with matching feature-id values will be commented out in the output. [Default: null]
658-
--output <string?> Optional: Output directory for rendered files. Defaults to current directory [Default: null]
659-
--subsections Optional: Group entries by area/component in subsections. For breaking changes with a subtype, groups by subtype instead of area. Defaults to false
660-
--title <string?> Optional: Title to use for section headers in output files. Defaults to version from first bundle [Default: null]
661-
```
555+
For up-to-date details, use the `-h` command option or refer to [](/cli/release/changelog-render.md).
662556

663557
Before you can use this command you must create changelog files and collect them into bundles.
664558
For example, the `docs-builder changelog bundle` command creates a file like this:

0 commit comments

Comments
 (0)