Skip to content

[DOCS] Edit changelog creation page #3170

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

Merged
lcawl merged 7 commits into from
Apr 29, 2026
Merged

[DOCS] Edit changelog creation page #3170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4fe1b1b
[DOCS] Edit changelog creation how-to
lcawl Apr 23, 2026
a5a3854
Remove some unnecessary examples
lcawl Apr 23, 2026
8149c4f
Clean up release note extraction details
lcawl Apr 23, 2026
b854725
Merge branch 'main' into changelog-edits1
lcawl Apr 29, 2026
b2d0b40
Final edits
lcawl Apr 29, 2026
39a6761
Update docs/contribute/configure-changelogs-ref.md
lcawl Apr 29, 2026
4132938
Update docs/cli/changelog/add.md
lcawl Apr 29, 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
125 changes: 84 additions & 41 deletions docs/cli/changelog/add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,7 @@ docs-builder changelog add [options...] [-h|--help]

`--no-extract-release-notes`
: Optional: Turn off extraction of release notes from PR or issue descriptions.
: The extractor looks for content in various formats in the PR or issue description:
: - `Release Notes: ...`
: - `Release-Notes: ...`
: - `release notes: ...`
: - `Release Note: ...`
: - `Release Notes - ...`
: - `## Release Note` (as a markdown header)
: 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.
: By default, the behavior is determined by the `extract.release_notes` changelog configuration setting.
: By default, the behavior is determined by the [extract.release_notes](/contribute/configure-changelogs-ref.md#extract) changelog configuration setting.

`--feature-id <string?>`
: Optional: Feature flag ID
Expand Down Expand Up @@ -76,8 +68,7 @@ docs-builder changelog add [options...] [-h|--help]
: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`).
: The valid product identifiers are listed in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
: The valid lifecycles are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
: **Precedence when `--products` is not specified:** products are derived from PR/issue labels via `pivot.products` label mappings (if configured), then from `products.default` in `changelog.yml`, and finally inferred from the current git repository name. An error is raised if no products can be determined by any of these means.
: Refer to [Products resolution](#products-resolution) in the how-to guide for full details.
: For more information about the valid product and lifecycle values, go to [Product format](#product-format).

`--prs <string[]?>`
: Optional: 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.
Expand Down Expand Up @@ -123,10 +114,90 @@ 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 PR numbers for filenames instead of the configured `filename` strategy. 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`.
: Optional: Use PR numbers for filenames instead of the configured `filename` strategy.
: Requires `--prs` or `--issues`.
: Mutually exclusive with `--use-issue-number`.
: Refer to [](#filenames).

`--use-issue-number`
: Optional: Use issue numbers for filenames instead of the configured `filename` strategy. 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`.
: Optional: Use issue numbers for filenames instead of the configured `filename` strategy.
: Requires `--prs` or `--issues`.
: Mutually exclusive with `--use-pr-number`.
: Refer to [](#filenames).

## Filenames

By default, output files are named according to the `filename` strategy in `changelog.yml`:

| Strategy | Example filename | Description |
|---|---|---|
| `timestamp` (default) | `1735689600-fixes-enrich-and-lookup-join-resolution.yaml` | Uses a Unix timestamp with a sanitized title slug. |
| `pr` | `137431.yaml` | Uses the PR number. |
| `issue` | `2571.yaml` | Uses the issue number. |

Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) or [](/contribute/configure-changelogs-ref.md).

You can override those settings with the `--use-pr-number` or `--use-issue-number` CLI flags:

```sh
docs-builder changelog add \
--prs 1234 \
--products "elasticsearch 9.2.3" \
--use-pr-number

docs-builder changelog add \
--issues 4567 \
--products "elasticsearch 9.3.0" \
--use-issue-number
```

:::{important}
`--use-pr-number` and `--use-issue-number` are mutually exclusive; specify only one. Each requires `--prs` or `--issues`. The numbers are extracted from the URLs or identifiers you provide or from linked references in the issue or PR body when extraction is enabled.

**Precedence**: CLI flags (`--use-pr-number` / `--use-issue-number`) > `filename` in `changelog.yml` > default (`timestamp`).
:::

## Product format and resolution [product-format]

The `--products` command option accepts values with the format `"product target lifecycle, ..."` where:

- `product` is a product ID that exists in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required)
- `target` is the target version or date (optional)
- `lifecycle` exists in [Lifecycle.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs) (optional)

You can further limit the possible values with the [products](/contribute/configure-changelogs-ref.md#products) and [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) options in the changelog configuration file.

For example:

- `"kibana 9.2.0 ga"`
- `"cloud-serverless 2025-08-05"`
- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"`

The `changelog add` command resolves product values in the following order:

1. The `--products` CLI option always takes priority.
1. If `pivot.products` is defined in the changelog configuration file and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied.
1. If `products.default` is defined in the changelog configuration file, those default products are used.
1. If `--repo` is specified (or `bundle.repo` is set in the changelog configuration file), the repository name is matched against known product IDs in `products.yml` and the derived value is used.

If none of these steps yield at least one product, the command returns an error.

## Configuration checks

By default, the command checks the following path for a configuration file: `docs/changelog.yml`.
You can specify a different path with the `--config` command option.

If a configuration file exists, the command validates its values before generating changelog files:

- If the configuration file contains `lifecycles`, `products`, `subtype`, or `type` values that don't match the values in `ChangelogEntryType.cs`, `ChangelogEntrySubtype.cs`, or `Lifecycle.cs`, validation fails.
- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails.
- If the configuration file contains `lifecycles` or `products` values that are a subset of the available values and you try to create a changelog with values outside that subset, validation fails.

In each of these cases where validation fails, a changelog file is not created.

If the configuration file contains `rules.create` definitions and a PR or issue has a blocking label, that PR is skipped and no changelog file is created for it.
For more information, refer to [Rules for creation and publishing](/contribute/configure-changelogs.md#rules).


## CI auto-detection [ci-auto-detection]

Expand Down Expand Up @@ -157,31 +228,3 @@ This allows the CI action to invoke `changelog add` with a minimal command line:
```sh
docs-builder changelog add --config docs/changelog.yml --output /tmp/staging --concise --strip-title-prefix
```

## Products resolution [products-resolution]

When you run the `changelog add` command without the `--products` option, it resolves products in the following order:

1. **`--products` CLI option** — always takes priority.
2. **`pivot.products` label mapping** — if `pivot.products` is configured and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied.
3. **`products.default` in `changelog.yml`** — the configured default products are used.
4. **Repository name inference** — if `--repo` is specified (or `bundle.repo` is set in `changelog.yml`), the repository name is matched against known product IDs in `products.yml`.
5. **Error** — if none of the above resolves to at least one product, an error is raised.

Product-specific `rules.create` rules are evaluated *after* products are resolved from labels, so label-derived products correctly participate in per-product create rule checks.

## Configuration checks

By default, the command checks the following path for a configuration file: `docs/changelog.yml`.
You can specify a different path with the `--config` command option.

If a configuration file exists, the command validates its values before generating changelog files:

- If the configuration file contains `lifecycles`, `products`, `subtype`, or `type` values that don't match the values in `ChangelogEntryType.cs`, `ChangelogEntrySubtype.cs`, or `Lifecycle.cs`, validation fails.
- If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails.
- If the configuration file contains `lifecycles` or `products` values that are a subset of the available values and you try to create a changelog with values outside that subset, validation fails.

In each of these cases where validation fails, a changelog file is not created.

If the configuration file contains `rules.create` definitions and a PR or issue has a blocking label, that PR is skipped and no changelog file is created for it.
For more information, refer to [Rules for creation and publishing](/contribute/configure-changelogs.md#rules).
25 changes: 22 additions & 3 deletions docs/cli/changelog/bundle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ You must choose one method for determining what's in the bundle (`--all`, `--inp

`--input-products <List<ProductInfo>?>`
: Filter by products in the format "product target lifecycle, ...".
: For more information about the valid product and lifecycle values, go to [Product format](/contribute/create-changelogs.md#product-format).
: For more information about the valid product and lifecycle values, go to [Product format](#product-format).
: When specified, all three parts (product, target, lifecycle) are required but can be wildcards (`*`). Multiple comma-separated values are combined with OR: a changelog is included if it matches any of the specified product/target/lifecycle combinations. For example:

- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — include changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta
Expand Down Expand Up @@ -122,6 +122,7 @@ The `--input-products` option determines which changelog files are gathered for
`--output-products <List<ProductInfo>?>`
: Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...".
: This value replaces information that would otherwise be derived from changelogs.
: For more information about the valid product and lifecycle values, go to [Product format](#product-format).
: When `rules.bundle.products` per-product overrides are configured, `--output-products` also supplies the product IDs used to choose the **rule context product** (first alphabetically) for Mode 3. To use a different product's rules, run a separate bundle with only that product in `--output-products`. For details, refer to [Product-specific bundle rules](/contribute/configure-changelogs-ref.md#rules-bundle-products).

`--no-release-date`
Expand Down Expand Up @@ -211,6 +212,22 @@ If you specify a file path with a different extension (not `.yml` or `.yaml`), t
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.
:::

## Product format

The `changelog bundle` command has `--input-products` and `--output-products` options that accept values with the format `"product target lifecycle, ..."` where:

- `product` is the product ID from [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml) (required)
- `target` is the target version or date (optional)
- `lifecycle` exists in [Lifecycle.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs) (optional)

You can further limit the possible values with the [products](/contribute/configure-changelogs-ref.md#products) and [lifecycles](/contribute/configure-changelogs-ref.md#lifecycles) options in the changelog configuration file.

For example:

- `"kibana 9.2.0 ga"`
- `"cloud-serverless 2025-08-05"`
- `"cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"`

## 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 @@ -439,6 +456,7 @@ If you're using profile-based commands, they're affected by the following fields
: 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.
: Supports `{version}` and `{lifecycle}` placeholders that are substituted at runtime.
: Example: `"elasticsearch {version} {lifecycle}"`
: Refer to [](#product-format).

:::{note}
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.
Expand All @@ -457,6 +475,7 @@ The `products` field determines which changelog files are gathered for considera
: The `{lifecycle}` placeholder is substituted at runtime with the inferred lifecycle. For `source: github_release` profiles this comes from the release tag suffix. For standard profiles it comes from the version argument. Refer to [](#changelog-bundle-standard-profile-lifecycle) and [](#changelog-bundle-github-release-profile) for details.
: If you omit lifecycle from the pattern (for example, `"elasticsearch {version}"`), the lifecycle field is omitted from the products array entirely.
: Example: `"elasticsearch {version} {lifecycle}"` or `"elasticsearch {version} ga"` to hardcode GA regardless of tag.
: Refer to [](#product-format).

`repo`
: Optional. The GitHub repository name written to each product entry in the bundle. Used by the `{changelog}` directive to generate correct PR/issue links. Only needed when the product ID doesn't match the GitHub repository name. Overrides `bundle.repo` when set. Required when `source: github_release` is used and no `bundle.repo` default is set.
Expand All @@ -481,7 +500,7 @@ If your configuration file defines a standard profile (that is to say, not a Git
| `9.2.0-alpha.1` | `preview` |
| `9.2.0-preview.1` | `preview` |

For more information about acceptable product and lifecycle values, go to [Product format](/contribute/create-changelogs.md#product-format).
For more information about acceptable product and lifecycle values, go to [Product format](#product-format).

You can invoke those profiles with commands like this:

Expand Down Expand Up @@ -664,4 +683,4 @@ gh-release:
```

By default all changelogs that match PRs in the GitHub release notes are included in the bundle.
To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules).
To apply additional filtering by the changelog type, areas, or products, add `rules.bundle` [filters](#changelog-bundle-rules).
3 changes: 2 additions & 1 deletion docs/contribute/bundle-changelogs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@ docs-builder changelog bundle \
--input-products "cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta" <1>
```

1. Include all changelogs that have the `cloud-serverless` product identifier with target dates of either December 2 2025 (lifecycle `ga`) or December 6 2025 (lifecycle `beta`). For more information about product values, refer to [Product format](/contribute/create-changelogs.md#product-format).
1. Include all changelogs that have the `cloud-serverless` product identifier with target dates of either December 2 2025 (lifecycle `ga`) or December 6 2025 (lifecycle `beta`). For more information about product values, refer to [Product format](/cli/changelog/bundle.md#product-format).

You can use wildcards in any of the three parts:

Expand Down Expand Up @@ -594,3 +594,4 @@ docs-builder changelog remove --products "elasticsearch 9.3.0 *" --dry-run
```

For full option details, go to [](/cli/changelog/remove.md).

Loading
Loading