Add PR label blockers to changelog creation

[lcawl]

Summary

This PR updates the docs-builder changelog add command to be able to create multiple changelog files if you provide multiple PRs in the --prs option. This makes it easier to address situations where we've missed changelogs for multiple PRs.

It also adds logic to block the creation of a changelog in the presence of chosen PR labels. This enables us to handle the situation where PRs have non-issue or release_notes:skip or any label of their choosing. It also enables us to handle the situation where changelogs are not desired for specific combinations of product and label (e.g. cloud-serverless and ILM).

[Edit] Upon further reflection, I think there are two circumstances: PR labels that block changelog creation and changelog areas that block inclusion in the docs (for a specific set of release notes). This PR only covers the first case. I've renamed the yaml entry to "add_blockers" so we can do a "render_blockers" in a subsequent PR (#2426).

Examples

If you have a changelog configuration file (changelog.yml) like this, which enables the command to derive the areas and types from PR labels:

# Available areas (optional - if not specified, all areas are allowed)
available_areas:
  - search
  - security
  - Aggregations
  - Network
  - Machine Learning
  - Vector Search
  - observability
  - index-management
  - ES|QL
  # Add more areas as needed

label_to_type:
  # Example mappings - customize based on your label naming conventions
  ">enhancement": enhancement
  ">breaking": breaking-change
  ">bug": bug-fix
  ">refactoring": other

# 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
  ":Search Relevance/ES|QL": "ES|QL"
  ":Analytics/Aggregations": "Aggregations"
  ":Distributed Coordination/Network": "Network"
  ":ml": "Machine Learning"
  ":Search Relevance/Vectors": "Vector Search"

Create changelogs for multiple PRs at once:

./docs-builder changelog add --prs 108875,135873,136886,140140 --repo elasticsearch --owner elastic --products "elasticsearch 9.2.2" --config ~/Documents/GitHub/elasticsearch/docs/changelog.yml

The command successfully creates three changelogs.

If you then update the changelog.yml configuration file to include add_blockers, for example:

add_blockers:
  elasticsearch, cloud-serverless:
    - ">non-issue"
    - ">test"

NOTE: The implementation supports two formats:

• Individual product IDs: elasticsearch: - ">non-issue"
• Comma-separated product IDs: elasticsearch, cloud-serverless: - ">non-issue"

The comma-separated format expands to individual entries during YAML deserialization, so both formats work identically.

Then the same docs-builder changelog add command returns the following messages:

info ::e.d.s.ChangelogService:: Processed 3 PR(s) successfully, skipped 1 PR(s)
warn ::d.b.d.Log             :: Skipping changelog creation for PR 140140 due to blocking label '>test' for product 'elasticsearch'. This label is configured to prevent changelog creation for this product.

Additional examples of area mappings can be found in:

• [DOCS] Add changelog configuration file kibana#247875
• [DOCS] Add changelog configuration file elasticsearch#140141
• https://github.com/elastic/elasticsearch-serverless/pull/5156

Changes

Summary

1. Changed --pr to --prs option

• Updated ChangelogCommand.cs to accept --prs as a string array
• Updated ChangelogInput to use Prs (string array) instead of Pr (string)
• Added comma-separated parsing support for PRs

2. Multiple PRs support

• Modified ChangelogService to process multiple PRs
• Creates one changelog file per PR when multiple PRs are provided
• Each PR is processed independently with its own title, type, and areas derived from GitHub

3. Product-specific label blocking

• Added AddBlockers configuration to ChangelogConfiguration
• Implemented blocking logic that checks PR labels against product-specific blocker lists
• If a PR has a blocking label for any specified product, changelog creation is skipped for that PR
• Clear warning messages indicate which PRs were skipped and why
• Added post-processing to expand comma-separated product IDs (e.g., elasticsearch, cloud-serverless) into individual entries

4. Tests

• Added test for multiple PRs creating multiple files
• Added test for label blocking preventing changelog creation
• Added test for product-specific blocking (e.g., cloud-serverless with ILM label)
• Added test for mixed scenario (some PRs blocked, some not)
• Updated existing tests to use Prs instead of Pr
• Added a test for comma-separated product IDs in add_blockers.

5. Documentation updates

• Updated changelog.yml.example with add_blockers configuration examples
• Updated docs/contribute/changelog.md to document the --prs option and label blocking feature
• All references to --pr updated to --prs

6. Error messages

• Clear error messages for validation failures
• Warning messages when PRs are skipped due to label blockers
• Messages include PR URL and blocking label information

All tests pass and the code builds successfully. The implementation follows the existing codebase patterns and maintains backward compatibility by supporting single PR processing when only one PR is provided.

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

[github-actions]

🔍 Preview links for changed docs

• docs/cli/index.md
• docs/cli/release/changelog-add.md
• docs/cli/release/index.md
• docs/contribute/changelog.md

[cotti]

This part looks good taking into account #2407's fixes; once it is merged here, we can merge this too IMO.

[Mpdreamz]

Can you explain the need for render blockers?

Ultimately these yaml changelog items will all go in to a database where they can be rendered in different views.

Put differently when do we need a changelog item that we never want exposed?

[lcawl]

Can you explain the need for render blockers?

I've responded to this in #2426 (comment)