Add changelog bundle and render commands

config/changelog.yml.example

@@ -4,16 +4,16 @@
 
 # Available types for changelog entries
 available_types:
-  - feature
-  - enhancement
-  - bug-fix
-  - known-issue
   - breaking-change
+  - bug-fix
   - deprecation
   - docs
+  - enhancement
+  - feature
+  - known-issue
+  - other
   - regression
   - security
-  - other
 
 # Available subtypes for breaking changes
 available_subtypes:
@@ -34,47 +34,62 @@ available_lifecycles:
 
 # Available areas (optional - if not specified, all areas are allowed)
 available_areas:
-  - search
-  - security
-  - machine-learning
-  - observability
-  - index-management
+  # - Autoscaling
+  # - Search
+  # - Security
+  # - Watcher
   # Add more areas as needed
 
 # Available products (optional - if not specified, all products are allowed)
 available_products:
-  - elasticsearch
-  - kibana
-  - apm
-  - beats
-  - elastic-agent
-  - fleet
-  - cloud-hosted
-  - cloud-serverless
-  - cloud-enterprise
+  # - elasticsearch
+  # - kibana
+  # - apm
+  # - beats
+  # - elastic-agent
+  # - fleet
+  # - cloud-hosted
+  # - cloud-serverless
+  # - cloud-enterprise
   # Add more products as needed
 
 # GitHub label mappings (optional - used when --pr option is specified)
 # Maps GitHub PR labels to changelog type values
 # When a PR has a label that matches a key, the corresponding type value is used
 label_to_type:
   # Example mappings - customize based on your label naming conventions
-  # "type:feature": feature
-  # "type:bug": bug-fix
-  # "type:enhancement": enhancement
-  # "type:breaking": breaking-change
-  # "type:security": security
+  # ">breaking": breaking-change
+  # ">bug": bug-fix
+  # ">docs": docs
+  # ">enhancement": enhancement
+  # ">feature": feature
 
 # Maps GitHub PR labels to changelog area values
 # Multiple labels can map to the same area, and a single label can map to multiple areas (comma-separated)
 label_to_areas:
   # Example mappings - customize based on your label naming conventions
-  # "area:search": search
-  # "area:security": security
-  # "area:ml": machine-learning
-  # "area:observability": observability
-  # "area:index": index-management
-  # "area:multiple": "search, security"  # Multiple areas comma-separated
+  # ":Distributed Coordination/Autoscaling": Autoscaling
+  # ":Search/Search": Search
+  # ":Security/Security": Security
+  # ":Data Management/Watcher": Watcher
+  # "area:multiple": "Search, Security"  # Multiple areas comma-separated
+
+# Render blockers (optional - used by the "docs-builder changelog render" command)
+# Changelogs matching the specified products and areas/types will be commented out in rendered output files
+# Dictionary key can be a single product ID or comma-separated product IDs (e.g., "elasticsearch, cloud-serverless")
+# Dictionary value contains areas and/or types that should be blocked for those products
+render_blockers:
+  # Multiple products (comma-separated) with areas and types that should be blocked
+  "cloud-hosted, cloud-serverless":
+    areas: # List of area values that should be blocked (commented out) during render
+      - Autoscaling
+      - Watcher
+    types: # List of type values that should be blocked (commented out) during render
+      - docs
+  # Single product with areas that should be blocked
+  elasticsearch:
+    areas:
+      - Security
 
 # Product-specific label blockers (optional)
 # Maps product IDs to lists of pull request labels that prevent changelog creation for that product

docs/_docset.yml

@@ -1,3 +1,3 @@
 project: 'doc-builder'
 max_toc_depth: 2
 # indicates this documentation set is not linkable by assembler.
@@ -160,6 +160,8 @@
         children:
           - file: index.md
           - file: changelog-add.md
+          - file: changelog-bundle.md
+          - file: changelog-render.md
   - folder: mcp
     children:
       - file: index.md

docs/cli/release/changelog-bundle.md

@@ -0,0 +1,61 @@
+# changelog bundle
+
+Bundle changelog files.
+
+To create the changelogs, use [](/cli/release/changelog-add.md).
+<!--
+For details and examples, go to [](/contribute/changelog.md).
+-->
+
+## Usage
+
+```sh
+docs-builder changelog bundle [options...] [-h|--help]
+```
+
+## Options
+
+`--all`
+:   Include all changelogs from the directory.
+:   Only one filter option can be specified: `--all`, `--input-products`, or `--prs`.
+
+`--directory <string?>`
+:   Optional: The directory that contains the changelog YAML files.
+:   Defaults to the current directory.
+
+`--input-products <List<ProductInfo>?>`
+:   Filter by products in format "product target lifecycle, ..."
+:   Only one filter option can be specified: `--all`, `--input-products`, or `--prs`.
+:   When specified, all three parts (product, target, lifecycle) are required but can be wildcards (`*`). For example:
+
+- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` - exact matches
+- `"cloud-serverless 2025-12-02 *"` - match cloud-serverless 2025-12-02 with any lifecycle
+- `"elasticsearch * *"` - match all elasticsearch changelogs
+- `"* 9.3.* *"` - match any product with target starting with "9.3."
+- `"* * *"` - match all changelogs (equivalent to `--all`)
+
+`--output <string?>`
+:   Optional: The output path for the bundle.
+:   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.
+
+`--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 by derived from changelogs.
+
+`--owner <string?>`
+:   The GitHub repository owner, which is required when pull requests are specified as numbers.
+
+`--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`.
+:   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.
+
+`--repo <string?>`
+:   The GitHub repository name, which is required when PRs are specified as numbers.
+
+`--resolve`
+:   Optional: Copy the contents of each changelog file into the entries array.
+:   By default, the bundle contains only the file names and checksums.

docs/cli/release/changelog-render.md

@@ -0,0 +1,53 @@
+# changelog render
+
+Generate markdown files from changelog bundle files.
+
+To create the bundle files, use [](/cli/release/changelog-bundle.md).
+
+For details and examples, go to [](/contribute/changelog.md).
+
+## Usage
+
+```sh
+docs-builder changelog render [options...] [-h|--help]
+```
+
+## Options
+
+`--input <string[]>`
+:   One or more bundle input files.
+:   Each bundle is specified as "bundle-file-path|changelog-file-path|repo|link-visibility" using pipe (`|`) as delimiter.
+:   To merge multiple bundles, separate them with commas: `--input "bundle1|dir1|repo1|keep-links,bundle2|dir2|repo2|hide-links"`.
+:   For example, `--input "/path/to/changelog-bundle.yaml|/path/to/changelogs|elasticsearch|keep-links"`.
+:   Only `bundle-file-path` is required for each bundle.
+:   Use `repo` if your changelogs do not contain full URLs for the pull requests or issues; otherwise they will be incorrectly derived with "elastic/elastic" in the URL by default.
+:   Use `link-visibility` to control whether PR/issue links are shown or hidden for entries from this bundle. Valid values are `keep-links` (default) or `hide-links`. Use `hide-links` for bundles from private repositories.
+:   **Important**: Paths must be absolute or use environment variables. Tilde (`~`) expansion is not supported.
+
+`--output <string?>`
+:   Optional: The output directory for rendered markdown files.
+:   Defaults to current directory.
+
+`--title <string?>`
+:   Optional: The title to use for section headers, directories, and anchors in output markdown files.
+:   Defaults to the version in the first bundle.
+:   If the string contains spaces, they are replaced with dashes when used in directory names and anchors.
+
+`--subsections`
+:   Optional: Group entries by area in subsections.
+:   Defaults to false.
+
+`--hide-features <string[]?>`
+:   Optional: Filter by feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs. Can be specified multiple times.
+:   Each occurrence can be either comma-separated feature IDs (e.g., `--hide-features "feature:new-search-api,feature:enhanced-analytics"`) or a file path (e.g., `--hide-features /path/to/file.txt`).
+:   When specifying feature IDs directly, provide comma-separated values.
+:   When specifying a file path, provide a single value that points to a newline-delimited file. The file should contain one feature ID per line.
+:   Entries with matching `feature-id` values will be commented out in the markdown output and a warning will be emitted.
+
+`--config <string?>`
+:   Optional: Path to the changelog.yml configuration file.
+:   Defaults to `docs/changelog.yml`.
+:   This configuration file is where the command looks for `render_blockers` details.
+
+You can configure `render_blockers` in your `changelog.yml` configuration file to automatically block changelog entries from being rendered based on their products, areas, and/or types.
+For more information, refer to [](/contribute/changelog.md#render-blockers).

docs/cli/release/index.md

@@ -7,3 +7,5 @@ navigation_title: "changelog"
 These commands are associated with product release documentation.
 
 - [changelog add](changelog-add.md) - Create a changelog file
+- [changelog bundle](changelog-bundle.md) - Create a changelog bundle file
+- [changelog render](changelog-render.md) - Generate markdown output from changelog bundle files