Fix and enhance changelog add command filename options

[lcawl]

Summary

While testing #2808, which affects the "changelog bundle" and "remove" commands, I also found some areas for improvement in the "changelog add" command.

1. Prevent "path too long" messages

changelog add --use-pr-number with many PRs builds a filename by joining all PR numbers with hyphens, e.g.:

224552-226849-228875-...-250532.yaml

With hundreds of PRs this can exceed filesystem limits and cause "path too long" or "component of the specified path is too long" errors.

Fix

ChangelogFileWriter.GenerateFilename now caps the filename length at 200 characters. If the hyphen‑separated list would exceed that, it uses a shorter form instead:

• Before: 224552-226849-228875-...-250532.yaml
• After: 224552-to-250532-300-prs.yaml (first PR, last PR, count, fixed suffix)

The same logic is applied for --use-issue-number when there are many issues.

2. Prevent creation of a single changelog when I run --prs with multiple values

This seems to be a regression, since it worked before in elastic/kibana#250840 but with new tests was creating a single changelog with hundreds of PRs in its array.

For multiple PRs with --use-pr-number, the service was calling CreateAggregatedChangelogAsync, which wrote a single changelog containing every PR. That was not the intended behavior.

Fix

1. Routing logic – Multiple PRs (with or without --use-pr-number) always go through CreateChangelogsForMultiplePrsAsync, so you get one changelog per PR.
2. --use-pr-number – When creating one file per PR, each file is named by its PR number (e.g. 224552.yaml, 226849.yaml, …).
3. Removal of CreateAggregatedChangelogAsync – That path only did the wrong behavior and is no longer used.

Behavior summary

1. Few PRs (filename ≤ 205 chars): still uses 137431-137432.yaml.
2. Many PRs (filename > 205 chars): uses {first}-to-{last}-{count}-prs.yaml.

3. Support --use-pr-number or --use-issue-number in all cases

Relax validation and updating docs so --use-issue-number works with --prs when issues are extracted from the PR body. And likewise there's no reason we shouldn't allow --use-pr-number when --issues is specified.

Summary of changes:

1. Validation (ChangelogCommand.cs)

   • --use-issue-number and --use-pr-number now work with both --prs or --issues

2. ChangelogCommand param

   • Help text updated to describe both modes

3. changelog-add.md and contribute/changelog.md

   • Same two-mode description for --use-issue-number.
   • Example added for --prs with --use-issue-number.
   • Important note changed so both flags “require --prs or --issues” instead of only requiring --issues.

Testing

To test these changes, I ran the following commands:

1. Check out Kibana release notes test kibana#250840 to get a list of PRs.
2. Verify that you can successfully create multiple changelogs from a list of PRs. For example:

   docs-builder changelog add \
   --prs ~/Documents/GitHub/kibana/docs/9.3.0-security.txt \
   --repo kibana --owner elastic --products "kibana 9.3.0, security 9.3.0" \
   --config ~/Documents/GitHub/kibana/docs/changelog.yml \
   --output ~/Documents/GitHub/kibana/docs/changelog/ \
   --use-pr-number --strip-title-prefix

   Prior to this PR, it generated a message like this:

   System.IO.PathTooLongException: The path '/path/to/GitHub/kibana/docs/changelog/233289-234793-236051-236110-236318-236756-236906-236992-237038-23...9032-249500-249891.yaml' is too long, or a component of the specified path is too long.

3. Verify that all combinations of --use-issue-number, and --use-pr-number work. For example:

   docs-builder changelog add \
   --prs 240272 --repo kibana --owner elastic \
   --products "kibana 9.3.0, security 9.3.0" \
   --config ~/Documents/GitHub/kibana/docs/changelog.yml \
   --output ~/Documents/GitHub/kibana/docs/changelog/

   • If I add --use-issue-number, the filename is 11085-14116.yaml.
   • If I add --use-pr-number, the filename is 240272.yaml.
   • If I don't add either option, the filename is 1772482097-[telemetry]-create-cloud-connector-usage-collector.yaml
4. Verify that the command can handle the (unlikely) scenario where both --prs and --issues are specified, with either --use-pr-number or --use-issue-number. For example:

   docs-builder changelog add \
   --prs 240272 --repo kibana --owner elastic \
   --products "kibana 9.3.0" \
   --config ~/Documents/GitHub/kibana/docs/changelog.yml \
   --output ~/Documents/GitHub/kibana/docs/changelog/ \
   --issues https://github.com/elastic/docs-builder/issues/2775  \
   --use-issue-number

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.5