Add changelog bundle and render commands

[lcawl]

Summary

• Added a docs-builder changelog bundle command that collects one or more changelogs into a single YAML file (to align with a product release).
• Added a docs-builder changelog render command that generates Docs V3-friendly markdown files from one or more changelog bundles.

Impetus

The goal is to have a stop-gap way to:

1. create files like https://github.com/elastic/elastic-agent/blob/main/changelog/9.2.2.yaml and https://github.com/elastic/elasticsearch/blob/main/docs/release-notes/changelog-bundles/9.2.2.yml (which were created by the elastic-agent-changelog-tool build and gradlew bundleChangelogs commands respectively).
2. create files like https://github.com/elastic/elastic-agent/tree/main/docs/release-notes and https://github.com/elastic/elasticsearch/tree/main/docs/release-notes (which were created or updated by the elastic-agent-changelog-tool render and gradlew generateReleaseNotes commands respectively)

Behaviour

The bundle command can create the list based on (a) all changelogs in a folder, (b) changelogs that have specific product and target values, (c) changelogs that have specific PR values. Only (a) was existing functionality. The long-term goal is to have these manifests generated from the list of PRs associated with a github release or deployment event (then optionally add known issues and security issues and remove feature-flagged changelogs as desired).

Examples

An example of the use of both the bundle and render commands can be found in https://github.com/elastic/cloud/pull/150210

Bundle

Bundle a list of PRs

You can use the --prs option (with the --repo and --owner options if you provide only the PR numbers) to create a bundle of the changelogs that relate to those pull requests. For example:

./docs-builder changelog bundle --prs 108875,135873,136886 --repo elasticsearch --owner elastic

Bundle by PRs in file

The --prs option also supports the use of a file that lists the PRs.
For example, if you have a file with the following PR URLs:

https://github.com/elastic/elasticsearch/pull/108875
https://github.com/elastic/elasticsearch/pull/135873
https://github.com/elastic/elasticsearch/pull/136886
https://github.com/elastic/elasticsearch/pull/137126

Run the bundle command to reference this file and explicitly set the bundle's product metadata:

./docs-builder changelog bundle --prs test/9.2.2a.txt --output-products "elasticsearch 9.2.2"

Alternatively, if the file contains just a list of PR numbers, you must specify the --repo and --owner options:

./docs-builder changelog bundle --prs test/9.2.2b.txt --output-products "elasticsearch 9.2.2" \
  --repo elasticsearch --owner elastic

Both variations create a bundle like this:

products:
- product: elasticsearch
   target: 9.2.2
entries:
- file:
    name: 1765507819-fix-ml-calendar-event-update-scalability-issues.yaml
    checksum: 069b59edb14594e0bc3b70365e81626bde730ab7
- file:
    name: 1765507798-convert-bytestransportresponse-when-proxying-respo.yaml
    checksum: c6dbd4730bf34dbbc877c16c042e6578dd108b62
- file:
    name: 1765507839-use-ivf_pq-for-gpu-index-build-for-large-datasets.yaml
    checksum: 451d60283fe5df426f023e824339f82c2900311e
- file:
    name: 1765507778-break-on-fielddata-when-building-global-ordinals.yaml
    checksum: 70d197d96752c05b6595edffe6fe3ba3d055c845

In this example, none of the changelogs had target or lifecycle product values, therefore there's no version info in this bundle.

Bundle by product and target

If you specify the --input-products option, the bundle contains only changelogs that contain one or more of the specified values:

docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 ga"

NOTE: As of #2429 you must always specify "product target lifecycle" (or else a wildcard asterisk).

Even if the changelogs also have other product values, only those specified in the bundle command appear in the output:

products:
- product: cloud-serverless
  target: 2025-12-02
- product: cloud-serverless
  target: 2025-12-06
entries:
- file:
    name: 1765495972-fixes-enrich-and-lookup-join-resolution-based-on-m.yaml
    checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464
- file:
    name: 1-test.yaml
    checksum: 0229ff4e908a0392af00e0905db94134616e6457

Bundle all changelog files

./docs-builder changelog bundle --directory . --all

NOTE: If you have changelogs that apply to multiple products and/or versions in your directory, this can result in a potentially unrealistic bundle. This command option was added to replicate existing behaviour in the elastic-agent-changelog-tool build and gradlew bundleChangelog commands and will likely be deprecated.

products:
- product: cloud-serverless
  target: 2025-12-02
- product: elasticsearch
  target: 9.2.3
- product: elasticsearch
  target: 9.3.0
- product: kibana
entries:
- file:
    name: 1765319409-fixes-enrich-and-lookup-join-resolution-based-on-m.yaml
    checksum: a01d40dc3673d681452373e5b78d1f01da609ff7
- file:
    name: 1765415340-[es|ql]-take-top_snippets-out-of-snapshot.yaml
    checksum: 4be2d3a14154b432f3a1d83ebfbd5568c69cbd1d
...

Copy the changelogs into the bundle

To include the contents of the changelogs, use the --resolve option:

./docs-builder changelog bundle --prs 108875,135873,136886 --repo elasticsearch --owner elastic --output-products "elasticsearch 9.2.2" --resolve

This generates output that's similar to the existing Elastic Agent bundles, for example https://github.com/elastic/elastic-agent/blob/main/changelog/9.2.2.yaml

products:
- product: elasticsearch
   target: 9.2.2
entries:
- file:
    name: 1765507819-fix-ml-calendar-event-update-scalability-issues.yaml
    checksum: 069b59edb14594e0bc3b70365e81626bde730ab7
  type: bug-fix
  title: Fix ML calendar event update scalability issues
  products:
  - product: elasticsearch
  areas:
  - Machine Learning
  pr: https://github.com/elastic/elasticsearch/pull/136886
...

The command is ready to use. Build succeeds and the help text displays correctly.

Render

For example, if you have a bundle like this:

products:
- product: elasticsearch
  target: 9.2.2
entries:
- file:
    name: 1765581721-convert-bytestransportresponse-when-proxying-respo.yaml
    checksum: d7e74edff1bdd3e23ba4f2f88b92cf61cc7d490a
- file:
    name: 1765581721-fix-ml-calendar-event-update-scalability-issues.yaml
    checksum: dfafce50c9fd61c3d8db286398f9553e67737f07
- file:
    name: 1765581651-break-on-fielddata-when-building-global-ordinals.yaml
    checksum: 704b25348d6daff396259216201053334b5b3c1d

You can render it to markdown files as follows:

./docs-builder changelog render \
  --input "changelog-bundle.1.yaml"
  --title 9.2.2 --output ./release-notes

The command merges all bundles, resolves file references using each bundle's directory, uses the appropriate repo for PR/issue links, and renders markdown files with the specified title.

For example, it generates a 9.2.2 folder in the specified output directory and creates breaking-changes.md, deprecations.md, and index.md files. The index.md file in this case contains:

## 9.2.2 [elastic-release-notes-9.2.2]

### Fixes [elastic-9.2.2-fixes]
* Convert BytesTransportResponse when proxying response from/to local node. [#135873](https://github.com/elastic/elastic/pull/135873) 
* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) 
* Break on FieldData when building global ordinals. [#108875](https://github.com/elastic/elastic/pull/108875) 

If you add the --subsections option to the command, the output changes as follows:

## 9.2.2 [elastic-release-notes-9.2.2]

### Fixes [elastic-9.2.2-fixes]

**Network**
* Convert BytesTransportResponse when proxying response from/to local node. [#135873](https://github.com/elastic/elastic/pull/135873) 

**Machine Learning**
* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) 

**Aggregations**
* Break on FieldData when building global ordinals. [#108875](https://github.com/elastic/elastic/pull/108875) 

There is a --hide-features to comment out changelogs that match specific feature-id values per #2412.

There is also --hide-private-links to comment out the PR and issue URLs for cases where we're working in private repos per #2408.

Finally, the command also supports the use of a --config option and heeds the presence of a render_blockers definition if we want to comment out changelogs that match specific area or type values per #2426.

These output files can be integrated into existing release note docs by using file inclusions. For example, view https://github.com/elastic/cloud/pull/150210

Outstanding items

All known outstanding items have been addressed.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

3. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1 agent, claude-4.5-sonnet

[github-actions]

🔍 Preview links for changed docs

• docs/cli/release/changelog-bundle.md
• docs/cli/release/changelog-render.md
• docs/cli/release/index.md
• docs/contribute/changelog.md
• docs/contribute/index.md