Add support for issue-centric changelogs

config/changelog.example.yml

@@ -27,8 +27,10 @@ extract:
   # Auto-extract release notes from PR descriptions (default: true)
   # Can be overridden by CLI --no-extract-release-notes
   release_notes: true
-  # Auto-extract issues from PR body (default: true)
-  # Looks for patterns like "Fixes #123", "Closes #456", etc.
+  # Auto-extract linked references (default: true)
+  # When using --prs: looks for patterns like "Fixes #123", "Closes #456" in PR body to derive issues.
+  # When using --issues: looks for patterns like "Fixed by #123" in issue body to derive PRs.
+  # Can be overridden by CLI --no-extract-issues
   issues: true
 
 # Available lifecycle values (strongly typed: preview, beta, ga)

docs/changelog/bundles/0.100.0.yaml

@@ -10,7 +10,8 @@ entries:
         target: 0.100.0
     areas:
       - CLI
-    pr: https://github.com/elastic/docs-builder/pull/2350
+    prs:
+      - https://github.com/elastic/docs-builder/pull/2350
     highlight: true
     description: |
       Adds support for configuring PR labels that block changelog creation.
@@ -25,7 +26,8 @@ entries:
         target: 0.100.0
     areas:
       - UI
-    pr: https://github.com/elastic/docs-builder/pull/2470
+    prs:
+      - https://github.com/elastic/docs-builder/pull/2470
     description: |
       Fixes an issue where HTMX navigation was not working correctly
       when selecting pages from the "Find Pages" dropdown menu.
@@ -36,7 +38,8 @@ entries:
         target: 0.100.0
     areas:
       - Build
-    pr: https://github.com/elastic/docs-builder/pull/2473
+    prs:
+      - https://github.com/elastic/docs-builder/pull/2473
     description: |
       Addresses F# nullability warnings in the codebase to improve
       code quality and reduce potential null reference issues.
@@ -47,7 +50,8 @@ entries:
         target: 0.100.0
     areas:
       - Assembler
-    pr: https://github.com/elastic/docs-builder/pull/2471
+    prs:
+      - https://github.com/elastic/docs-builder/pull/2471
     description: |
       Prevents speculative builds from running for repositories that are
       already publishing with non-versioned branches, avoiding unnecessary

docs/changelog/fsharp-nullability-warnings.yaml

@@ -5,7 +5,8 @@ products:
     target: 0.100.0
 areas:
   - Build
-pr: https://github.com/elastic/docs-builder/pull/2473
+prs:
+  - https://github.com/elastic/docs-builder/pull/2473
 description: |
   Addresses F# nullability warnings in the codebase to improve
   code quality and reduce potential null reference issues.

docs/changelog/htmx-navigation-fix.yaml

@@ -5,7 +5,8 @@ products:
     target: 0.100.0
 areas:
   - UI
-pr: https://github.com/elastic/docs-builder/pull/2470
+prs:
+  - https://github.com/elastic/docs-builder/pull/2470
 description: |
   Fixes an issue where HTMX navigation was not working correctly
   when selecting pages from the "Find Pages" dropdown menu.

docs/changelog/pr-label-blockers.yaml

@@ -5,7 +5,8 @@ products:
     target: 0.100.0
 areas:
   - CLI
-pr: https://github.com/elastic/docs-builder/pull/2350
+prs:
+  - https://github.com/elastic/docs-builder/pull/2350
 description: |
   Adds support for configuring PR labels that block changelog creation.
   This allows teams to mark PRs that should not generate changelog entries

docs/changelog/sample-feature-099.yaml

@@ -4,7 +4,8 @@ type: feature
 description: |
   Added CLI commands for managing release notes: `changelog add`, `changelog bundle`, and `changelog render`.
   This enables automated generation and formatting of release notes from structured YAML files.
-pr: "1234"
+prs:
+  - "1234"
 products:
   - product: docs-builder
     target: 0.99.0

docs/changelog/speculative-builds-fix.yaml

@@ -5,7 +5,8 @@ products:
     target: 0.100.0
 areas:
   - Assembler
-pr: https://github.com/elastic/docs-builder/pull/2471
+prs:
+  - https://github.com/elastic/docs-builder/pull/2471
 description: |
   Prevents speculative builds from running for repositories that are
   already publishing with non-versioned branches, avoiding unnecessary

docs/cli/release/changelog-add.md

@@ -48,16 +48,25 @@ docs-builder changelog add [options...] [-h|--help]
 :   If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (`\`).
 
 `--issues <string[]?>`
-:   Optional: Issue numbers (comma-separated or specify multiple times).
+:   Optional: Issue URL(s) or number(s) (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers. Can be specified multiple times.
+:   Each occurrence can be either comma-separated issues (e.g., `--issues "https://github.com/owner/repo/issues/123,456"`) or a file path (e.g., `--issues /path/to/file.txt`).
+:   When specifying issues 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, issue numbers can be used instead of URLs.
+:   If specified, `--title` can be derived from the issue.
+:   Creates one changelog file per issue.
 
 `--no-extract-issues`
-:   Optional: Turn off extraction of linked issues from PR body (for example, "Fixes #123"). By default, linked issues are extracted when using `--prs`.
+:   Optional: Turn off extraction of linked references.
+:   When using `--prs`: turns off extraction of linked issues from the PR body (for example, "Fixes #123").
+:   When using `--issues`: turns off extraction of linked PRs from the issue body (for example, "Fixed by #123").
+:   By default, linked references are extracted in both cases.
 
 `--output <string?>`
 :   Optional: Output directory for the changelog fragment. Defaults to current directory.
 
 `--owner <string?>`
-:   Optional: GitHub repository owner (used when `--pr` is just a number).
+:   Optional: GitHub repository owner (used when `--prs` or `--issues` contains just numbers).
 
 `--products <List<ProductInfo>>`
 :   Required: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`).
@@ -76,7 +85,7 @@ docs-builder changelog add [options...] [-h|--help]
 :   If there are `block ... create` definitions in the changelog configuration file and a PR has a blocking label for any product in `--products`, that PR is skipped and no changelog file is created for it.
 
 `--repo <string?>`
-:   Optional: GitHub repository name (used when `--pr` is just a number).
+:   Optional: GitHub repository name (used when `--prs` or `--issues` contains just numbers).
 
 `--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.
@@ -90,14 +99,25 @@ docs-builder changelog add [options...] [-h|--help]
 
 `--title <string>`
 :    A short, user-facing title (max 80 characters)
-:    Required if `--pr` is not specified.
-:    If both `--pr` and `--title` are specified, the latter value is used instead of what exists in the PR.
+:    Required if neither `--prs` nor `--issues` is specified.
+:    If both `--prs` and `--title` are specified, the latter value is used instead of what exists in the PR.
 :    If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (`\`).
 
 `--type <string>`
-:   Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).
+:   Required if neither `--prs` nor `--issues` is specified. Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).
+:   If mappings are configured, type can be derived from the PR or issue.
 :   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 the PR number as the filename instead of generating it from a unique ID and title.
-:   When using this option, you must also provide the `--pr` option.
+:   Optional: Use the PR number(s) as the filename instead of generating it from a timestamp and title.
+:   With multiple PRs, uses hyphen-separated numbers (for example, `137431-137432.yaml`).
+:   Requires `--prs`. Mutually exclusive with `--use-issue-number`.
+
+`--use-issue-number`
+:   Optional: Use the issue number(s) as the filename instead of generating it from a timestamp and title.
+:   With multiple issues, uses hyphen-separated numbers (for example, `12345-12346.yaml`).
+:   Requires `--issues`. When both `--issues` and `--prs` are specified, still uses the issue number for the filename if this flag is set. Mutually exclusive with `--use-pr-number`.
+
+:::{important}
+`--use-pr-number` and `--use-issue-number` are mutually exclusive; specify only one.
+:::

docs/cli/release/changelog-bundle.md

@@ -29,7 +29,7 @@ These arguments apply to profile-based bundling:
 
 `--all`
 :   Include all changelogs from the directory.
-:   Only one filter option can be specified: `--all`, `--input-products`, or `--prs`.
+:   Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
 
 `--config <string?>`
 :   Optional: Path to the changelog.yml configuration file.
@@ -46,7 +46,7 @@ These arguments apply to profile-based bundling:
 
 `--input-products <List<ProductInfo>?>`
 :   Filter by products in format "product target lifecycle, ..."
-:   Only one filter option can be specified: `--all`, `--input-products`, or `--prs`.
+:   Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
 :   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
@@ -55,6 +55,13 @@ These arguments apply to profile-based bundling:
 - `"* 9.3.* *"` - match any product with target starting with "9.3."
 - `"* * *"` - match all changelogs (equivalent to `--all`)
 
+`--issues <string[]?>`
+:   Filter by issue URLs or numbers (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers. Can be specified multiple times.
+:   Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
+:   Each occurrence can be either comma-separated issues (e.g., `--issues "https://github.com/owner/repo/issues/123,456"`) or a file path (e.g., `--issues /path/to/file.txt`).
+:   When specifying issues directly, provide comma-separated values.
+:   When specifying a file path, provide a single value that points to a newline-delimited file.
+
 `--no-resolve`
 :   Optional: Explicitly turn off the `resolve` option if it's specified in the changelog configuration file.
 
@@ -68,17 +75,17 @@ These arguments apply to profile-based bundling:
 :   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.
+:   The GitHub repository owner, which is required when pull requests or issues 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`.
+:   Only one filter option can be specified: `--all`, `--input-products`, `--prs`, or `--issues`.
 :   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.
+:   The GitHub repository name, which is required when pull requests or issues are specified as numbers.
 
 `--resolve`
 :   Optional: Copy the contents of each changelog file into the entries array.

docs/cli/release/changelog-render.md

@@ -33,7 +33,7 @@ docs-builder changelog render [options...] [-h|--help]
 :   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.
+:   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. When `hide-links` is set, all links are hidden for each affected entry — changelog entries can contain multiple PR links (`prs`) and issue links (`issues`), and all of them are hidden or shown together.
 :   Paths support tilde (`~`) expansion and relative paths.
 
 :::{note}
@@ -92,6 +92,14 @@ When `--file-type asciidoc` is specified, the command generates a single asciido
 
 The asciidoc output uses attribute references for links (for example, `{repo-pull}NUMBER[#NUMBER]`).
 
+### Multiple PR and issue links
+
+Changelog entries can reference multiple pull requests and issues using the `prs` and `issues` array fields. When an entry has multiple links, all of them are rendered inline for that entry:
+
+```md
+* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) [#136900](https://github.com/elastic/elastic/pull/136900)
+```
+
 ## Examples
 
 ### Render a single bundle

docs/contribute/_snippets/changelog-fields.md

@@ -70,10 +70,10 @@ issues:
 # They are externalized in the release docs so users can follow the links and
 # understand the context.
 
-pr: 
+prs:
 
-# An optional string that contains the pull request identifier.
-# It is externalized in the release docs so users can follow the link and find more details.
+# An optional array of pull request identifiers (URLs or numbers).
+# Each value is externalized in the release docs so users can follow the links and find more details.
 
 subtype: