Add file support to docs-builder changelog add --prs option

[lcawl]

Summary

• Added file path support to the docs-builder changelog add --prs option, allowing users to specify pull requests either as comma-separated values or via a file containing newline-delimited PR URLs or numbers.

This implementation matches the behavior of the docs-builder changelog bundle --prs option (per #2411 ), providing consistency across changelog commands.

Example

1. Create a file that contains a list of PRs. For example, use the list of PRs for 8.19.10:

   https://github.com/elastic/elasticsearch/pull/139679
   https://github.com/elastic/elasticsearch/pull/139712
   https://github.com/elastic/elasticsearch/pull/139442
   https://github.com/elastic/elasticsearch/pull/128429
   https://github.com/elastic/elasticsearch/pull/139966
   https://github.com/elastic/elasticsearch/pull/140118
   https://github.com/elastic/elasticsearch/pull/139989
   https://github.com/elastic/elasticsearch/pull/139569
   https://github.com/elastic/elasticsearch/pull/139788
   https://github.com/elastic/elasticsearch/pull/140046
   https://github.com/elastic/elasticsearch/pull/139894
   https://github.com/elastic/elasticsearch/pull/140149
   https://github.com/elastic/elasticsearch/pull/139221
   https://github.com/elastic/elasticsearch/pull/139669

2. Create a configuration file to handle the mapping of labels to areas, for example, use [DOCS] Add changelog configuration file elasticsearch#140141
3. Refresh the binaries, per https://github.com/elastic/docs-builder/blob/main/README.md. For example:

   ./build.sh clean
   ./build.sh publishbinaries
   cd .artifacts/publish/docs-builder/release/

4. Test the changelog command:

    ./docs-builder changelog add --prs ~/path/to/8.19.10.txt --repo elasticsearch --owner elastic --products "elasticsearch 8.19.10" --config ~/path/to/changelog.yml --output ~/path/to/elasticsearch/docs/changelog/new/

The command completes with the following message:

...
info ::e.d.s.ChangelogService:: Processed 13 PR(s) successfully, skipped 0 PR(s)

	The following errors and warnings were found in the documentation

Error: Cannot derive type from PR https://github.com/elastic/elasticsearch/pull/140046 labels (>non-issue, :Security/Authentication, Team:Security, external-contributor, auto-backport, Team:Cloud Security, v9.1.10, v9.2.4, v8.19.10, v9.3.1, v9.4.0). No matching label found in label_to_type mapping. Please provide --type or add a label mapping in changelog.yml.



	1 Errors / 0 Warnings / 0 Hints

This is an expected error, since the pull request had the >non-issue label. The rest of the changelogs were created successfully.

Changes Made

1. Command Implementation (src/tooling/docs-builder/Commands/ChangelogCommand.cs)

What Changed:

• Added System.IO.Abstractions using statement for file system operations
• Added _fileSystem field to the ChangelogCommand class
• Enhanced PR parsing logic to handle both file paths and comma-separated values
• Updated XML documentation comment for the --prs parameter

Key Implementation Details:

• The command now checks if each value in the --prs array is a file path (by checking if the file exists)
• If a file path is detected, it reads all lines from the file (newline-delimited)
• If not a file path, it treats the value as comma-separated PRs
• Multiple --prs arguments can be specified, mixing file paths and comma-separated values
• Error handling added for file reading failures

2. Documentation (docs/cli/release/changelog-add.md and docs/contribute/changelog.md)

What Changed:

• Updated the --prs option description to match the bundle command documentation
• Added details about:
  • File path support (newline-delimited files)
  • Multiple occurrences support
  • Mixing file paths and comma-separated values

3. Test Coverage (tests/Elastic.Documentation.Services.Tests/ChangelogServiceTests.cs)

What Changed:

• Added two new test methods to verify file path functionality:
  1. CreateChangelog_WithPrsFromFile_ProcessesAllPrsFromFile
  2. CreateChangelog_WithMixedPrsFromFileAndCommaSeparated_ProcessesAllPrs

Test 1: CreateChangelog_WithPrsFromFile_ProcessesAllPrsFromFile

• Creates a temporary file with 3 newline-delimited PR URLs
• Simulates reading PRs from the file (as ChangelogCommand would do)
• Verifies all PRs are processed and changelog files are created
• Verifies PR information is correctly extracted and included in changelogs

Test 2: CreateChangelog_WithMixedPrsFromFileAndCommaSeparated_ProcessesAllPrs

• Tests mixing file paths and comma-separated PRs
• Creates a file with one PR and adds another PR via comma-separated value
• Verifies both PRs are processed correctly
• Simulates the ChangelogCommand behavior of combining PRs from multiple sources

Behavior

File Path Detection

• The command checks if a value in --prs is a file path by calling File.Exists()
• If the file exists, it's treated as a file path
• If the file doesn't exist, it's treated as comma-separated PRs

File Format

• Files should contain one PR URL or number per line
• Empty lines are ignored
• Leading and trailing whitespace is trimmed from each line

Multiple --prs Arguments

• Users can specify --prs multiple times
• Each occurrence can be either:
  • A comma-separated list of PRs
  • A file path
• All PRs from all sources are combined and processed

Error Handling

• If a file cannot be read, an error is emitted and the command returns exit code 1
• The error message includes the file path and the exception message

Compatibility

This change is backward compatible:

• Existing usage with comma-separated PRs continues to work unchanged
• The new file path functionality is additive and doesn't break existing workflows

Usage Examples

Example 1: Using a file

# Create file with PRs
echo "https://github.com/elastic/elasticsearch/pull/1234" > prs.txt
echo "https://github.com/elastic/elasticsearch/pull/5678" >> prs.txt

# Use file
docs-builder changelog add --prs prs.txt \
  --products "elasticsearch 9.2.0 ga"

Example 2: Mixing file and comma-separated

docs-builder changelog add \
  --prs "https://github.com/elastic/elasticsearch/pull/1111" \
  --prs prs.txt \
  --prs "2222, 3333" \
  --products "elasticsearch 9.2.0 ga" \
  --owner elastic --repo elasticsearch

Example 3: Multiple files

docs-builder changelog add \
  --prs prs1.txt \
  --prs prs2.txt \
  --products "elasticsearch 9.2.0 ga"

Testing

All tests pass successfully:

• ✅ CreateChangelog_WithPrsFromFile_ProcessesAllPrsFromFile
• ✅ CreateChangelog_WithMixedPrsFromFileAndCommaSeparated_ProcessesAllPrs
• ✅ All existing changelog tests continue to pass

Verification

• ✅ Build succeeds with no errors
• ✅ All tests pass
• ✅ Code follows existing patterns and conventions
• ✅ Documentation updated and consistent
• ✅ Backward compatible with existing usage

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

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