Wildcard support in docs-builder changelog bundle --input-products

[lcawl]

This PR alters the "docs-builder changelog bundle" command that is added in #2341.

Impetus

The --input-products option for the docs-builder changelog bundle command currently performs only exact matching, which is not ideal since the target and lifecycle are not mandatory values in changelogs.

Summary

Updated the docs-builder changelog bundle command to require all three parts (product, target, lifecycle) when using --input-products, with wildcard support.
The command now supports three filter options: --all, --input-products, or --prs (only one at a time).

Behaviour

• When --input-products is used, all three parts (product, target, lifecycle) are required
• All three parts can be wildcards (*)
  ---input-products * * * is equivalent to --all
• Wildcard matching supports:
  • * matches any value (including null/empty)
  • Patterns ending with * (e.g., 9.3.*) do prefix matching
  • Exact matches are case-insensitive
• Deduplication: changelogs appear only once in bundles, even if they match multiple filters

Code Changes

src/tooling/docs-builder/Commands/ChangelogCommand.cs

• Updated validation to require exactly one of --all, --input-products, or --prs
• When --input-products is provided, validates all three parts are present (can be *)
• Converts --input-products * * * to --all internally

src/services/Elastic.Documentation.Services/ChangelogService.cs

• Updated filter validation to check for --all, --input-products, or --prs (only one)
• Implemented wildcard matching with MatchesPattern helper function:
  • null pattern = wildcard (matches anything)
  • Patterns ending with * = prefix matching
  • Exact matches = case-insensitive
• Updated product filtering to check product, target, and lifecycle against patterns
• Added deduplication using checksums to ensure each changelog appears only once

Testing

• ✅ All code compiles successfully
• ✅ No linting errors
• ✅ Tests updated and ready to run

Updated Tests (tests/Elastic.Documentation.Services.Tests/ChangelogServiceTests.cs)

• BundleChangelogs_WithProductsFilter_FiltersCorrectly: Added lifecycle requirement
• BundleChangelogs_WithNoFilterOption_ReturnsError: Changed from "includes all" to "returns error" (filter now required)
• BundleChangelogs_WithMultipleFilterOptions_ReturnsError: Added lifecycle requirement

New Tests Added

• BundleChangelogs_WithWildcardProductFilter_MatchesAllProducts: Tests product wildcard (*)
• BundleChangelogs_WithWildcardAllParts_EquivalentToAll: Tests * * * equivalent to --all
• BundleChangelogs_WithPrefixWildcardTarget_MatchesCorrectly: Tests prefix matching (9.3.*)

Documentation Updates

docs/contribute/changelog.md

• Updated --input-products description to explain all three parts are required when used
• Added wildcard support examples
• Documented * * * equivalent to --all
• Updated filter options section to list all three options
• Added examples for wildcard usage

Examples

Exact Match

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

Wildcard Lifecycle

docs-builder changelog bundle \
  --input-products "cloud-serverless 2025-12-02 *"

Prefix Matching

docs-builder changelog bundle \
  --input-products "elasticsearch 9.3.* *"

Match either product, any target, any lifecycle

docs-builder changelog bundle \
  --input-products "elasticsearch * *, kibana * *"

Equivalent to --all

docs-builder changelog bundle \
  --input-products "* * *"

Validation Rules

1. At least one filter must be specified: --all, --input-products, or --prs
2. Only one filter can be specified at a time
3. When --input-products is used:
   • Product cannot be empty (but can be *)
   • Target must be provided (can be *)
   • Lifecycle must be provided (can be *)

Technical Details

• Wildcard matching: Case-insensitive, supports prefix patterns
• Deduplication: Uses SHA1 checksums to identify duplicate changelogs

Addendums

Returning validation errors to command line

There was also a problem where when the command returns early (e.g., return 1), the diagnostics collector isn't started, so error messages aren't displayed. The error is emitted, but the collector only displays messages after it's started and stopped. A fix commit (65a19fa) was merged to update the command to start the collector, wait for diagnostics to drain, and stop it before returning early. This ensures error messages are displayed even when validation fails early.

Now when you run:

docs-builder changelog bundle --all --prs 108759

...you should see the full error message: Error: Multiple filter options cannot be specified together. You specified: --all, --prs. Please use only one filter option: --all, --input-products, or --prs.

Adding lifecycle to bundle metadata

When using --input-products, the products array is now extracted from the matched changelog entries, not from the filter values. So when you use --input-products "elasticsearch 9.2.0 *", the products array includes the actual lifecycle value (ga) from the changelog file, not the wildcard. In my initial tests, the lifecycle was missing from the products array in the bundle, even though it existed in one of the referenced changelogs.

The warning message is also now updated to include the lifecycle. For example:

./docs-builder changelog bundle --directory ./test-2 --input-products "elasticsearch 9.2.0 *"

...
info ::d.b.f.StopwatchFilter :: changelog bundle :: Starting...
info ::e.d.s.ChangelogService:: Found 10 YAML files in directory
info ::e.d.s.ChangelogService:: Found 3 matching changelog entries
warn ::d.b.d.Log             :: Product 'elasticsearch' has multiple targets in bundle: 9.2.0, 9.2.0 beta, 9.2.0 ga
info ::e.d.s.ChangelogService:: Created bundled changelog: ./test-2/changelog-bundle.yaml

	The following errors and warnings were found in the documentation

Warning: Product 'elasticsearch' has multiple targets in bundle: 9.2.0, 9.2.0 beta, 9.2.0 ga

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