|
2 | 2 |
|
3 | 3 | Bundle changelog files. |
4 | 4 |
|
5 | | -To create the changelogs, use [](/cli/release/changelog-add.md). |
| 5 | +To create the changelogs, use [](/cli/changelog/add.md). |
6 | 6 | For details and examples, go to [](/contribute/changelog.md). |
7 | 7 |
|
8 | 8 | ## Usage |
@@ -141,7 +141,7 @@ The `--input-products` option determines which changelog files are gathered for |
141 | 141 | : By default, the bundle contains only the file names and checksums. |
142 | 142 |
|
143 | 143 | `--sanitize-private-links` |
144 | | -: Optional: Turn on [private link sanitization](/cli/release/changelog-bundle.md#private-link-sanitization). |
| 144 | +: Optional: Turn on [private link sanitization](#private-link-sanitization). |
145 | 145 | : 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. |
146 | 146 | : This option requires a resolved bundle: use `--resolve` or set `bundle.resolve: true` in the `changelog.yml`. |
147 | 147 | : If sanitization is enabled and the bundle is not resolved, the command fails. |
@@ -372,6 +372,7 @@ If you're using profile-based commands, they're affected by the following fields |
372 | 372 |
|
373 | 373 | `products` |
374 | 374 | : Required when filtering by product metadata (equivalent to the `--input-products` command option). |
| 375 | +: The value `"* * *"` is equivalent to the `--all` command option. |
375 | 376 | : 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. |
376 | 377 | : Supports `{version}` and `{lifecycle}` placeholders that are substituted at runtime. |
377 | 378 | : Example: `"elasticsearch {version} {lifecycle}"` |
@@ -452,42 +453,64 @@ For example: |
452 | 453 |
|
453 | 454 | ```yaml |
454 | 455 | bundle: |
| 456 | + # Input directory containing changelog YAML files |
| 457 | + directory: docs/changelog |
| 458 | + # Output directory for bundles |
| 459 | + output_directory: docs/releases |
| 460 | + # Whether to resolve (copy contents) by default |
| 461 | + resolve: true |
455 | 462 | repo: elasticsearch <1> |
456 | 463 | owner: elastic |
457 | 464 | profiles: |
| 465 | + # Collect all changelogs |
| 466 | + release-all: |
| 467 | + products: "* * *" <2> |
| 468 | + output: "all.yaml" |
458 | 469 | # Find changelogs with any lifecycle and a partial date |
459 | 470 | serverless-monthly: |
460 | | - products: "cloud-serverless {version}-* *" <2> |
| 471 | + products: "cloud-serverless {version}-* *" <3> |
461 | 472 | output: "serverless-{version}.yaml" |
462 | 473 | output_products: "cloud-serverless {version}" |
463 | 474 |
|
464 | 475 | # Find changelogs with a specific lifecycle |
465 | 476 | elasticsearch-ga-only: |
466 | | - products: "elasticsearch {version} ga" <3> |
| 477 | + products: "elasticsearch {version} ga" <4> |
467 | 478 | output: "elasticsearch-{version}.yaml" |
468 | 479 |
|
469 | 480 | # Infer the lifecycle from the version |
470 | 481 | elasticsearch-release: |
471 | | - hide_features: <4> |
| 482 | + hide_features: <5> |
472 | 483 | - feature-flag-1 |
473 | 484 | - feature-flag-2 |
474 | | - products: "elasticsearch {version} {lifecycle}" <5> |
| 485 | + products: "elasticsearch {version} {lifecycle}" <6> |
475 | 486 | output: "elasticsearch-{version}.yaml" |
476 | 487 | output_products: "elasticsearch {version}" |
477 | 488 | ``` |
478 | 489 |
|
479 | 490 | 1. Bundle-level defaults that apply to all profiles. Individual profiles can override these. |
480 | | -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. |
481 | | -3. Bundles any changelogs that have `product: elasticsearch`, `lifecycle: ga`, and the version specified in the command. |
482 | | -4. Adds a `hide-features` array in the bundle. This is equivalent to the `--hide-features` command option. |
483 | | -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`). |
| 491 | +2. Collects all changelogs from the `directory`. This is equivalent to the `--all` command. |
| 492 | +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. |
| 493 | +4. Collects any changelogs that have `product: elasticsearch`, `lifecycle: ga`, and the version specified in the command. |
| 494 | +5. Adds a `hide-features` array in the bundle. This is equivalent to the `--hide-features` command option. |
| 495 | +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`). |
484 | 496 |
|
485 | 497 | `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. |
486 | 498 |
|
487 | 499 | :::{note} |
488 | 500 | 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. |
489 | 501 | ::: |
490 | 502 |
|
| 503 | +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: |
| 504 | + |
| 505 | +```sh |
| 506 | +# Profile with static patterns - second argument unused but required |
| 507 | +docs-builder changelog bundle release-all '*' |
| 508 | +docs-builder changelog bundle release-all 'unused' |
| 509 | +docs-builder changelog bundle release-all 'none' |
| 510 | +``` |
| 511 | + |
| 512 | +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. |
| 513 | + |
491 | 514 | ### Bundle by report or URL list [profile-bundle-report-examples] |
492 | 515 |
|
493 | 516 | You can also create profiles that are equivalent to the `--prs`, `--issues`, and `--report` filter options. |
|
0 commit comments