Add --extract-release-notes to changelog add

[lcawl]

Impetus

Fixes https://github.com/elastic/docs-eng-team/issues/370
In Kibana pull requests, contributors often put a "Release Notes" section in the PR description and it's heeded by their current https://github.com/elastic/kibana-release-notes generator.
I think we ought to have the same option in the docs-builder changelog add command (though not by default since this is the only team currently requiring that functionality).

Overview

Added support for extracting release notes from GitHub PR descriptions in the docs-builder changelog add command. This feature automatically extracts release notes from PR descriptions and uses them appropriately in changelog entries based on their length and format.

Implementation Summary

Core Changes

1. GitHub PR Service Updates

• File: src/services/Elastic.Documentation.Services/Changelog/GitHubPrService.cs
• Changes:
  • Added Body property to GitHubPrInfo class to store PR description
  • Updated GitHubPrResponse to include Body field from GitHub API
  • Modified FetchPrInfoAsync to populate the Body property

2. Release Notes Extractor Utility

• File: src/services/Elastic.Documentation.Services/Changelog/ReleaseNotesExtractor.cs (new)
• Features:
  • Extracts release notes from PR descriptions using regex patterns
  • Strips HTML comments before extraction
  • Supports multiple formats:
    • Release Notes: ...
    • Release-Notes: ...
    • release notes: ...
    • Release Note: ...
    • Release Notes - ...
    • ## Release Note (markdown header)
  • Uses GeneratedRegexAttribute for compile-time regex generation
  • Handles three scenarios:
    • No release note found: Returns nulls (no changes)
    • Short release note (≤120 chars, single line): Returns as title
    • Long release note (>120 chars or multi-line): Returns as description

3. Changelog Command Updates

• File: src/tooling/docs-builder/Commands/ChangelogCommand.cs
• Changes:
  • Added --extract-release-notes boolean option
  • Updated XML documentation to describe the new option
  • Passes the option through to ChangelogInput

4. Changelog Input Model

• File: src/services/Elastic.Documentation.Services/Changelog/ChangelogInput.cs
• Changes:
  • Added ExtractReleaseNotes boolean property

5. Changelog Service Logic

• File: src/services/Elastic.Documentation.Services/ChangelogService.cs
• Changes:
  • Added release notes extraction logic in CreateSingleChangelog method
  • Extracts release notes when ExtractReleaseNotes is enabled
  • Uses short release notes as title (only if title not explicitly provided)
  • Uses long release notes as description (only if description not explicitly provided)
  • Updated CreateChangelogsForMultiplePrs to pass ExtractReleaseNotes flag to individual PR processing

Documentation Updates

• Updated docs/cli/release/changelog-add.md and docs/contribute/changelog.md

Testing

Test Coverage

1. Release Notes Extractor Tests

• File: tests/Elastic.Documentation.Services.Tests/ReleaseNotesExtractorTests.cs (new)
• Test Count: 17 tests
• Coverage:
  • ✅ Various release note format patterns (colon, dash, markdown header, case variations)
  • ✅ HTML comment stripping
  • ✅ Multi-line extraction
  • ✅ Short vs long release note classification
  • ✅ Edge cases (null, empty, exactly 120 characters, 121 characters)
  • ✅ Boundary conditions

2. Changelog Service Integration Tests

• File: tests/Elastic.Documentation.Services.Tests/ChangelogServiceTests.cs
• Test Count: 6 new tests
• Coverage:
  • ✅ CreateChangelog_WithExtractReleaseNotes_ShortReleaseNote_UsesAsTitle - Verifies short release notes are used as title
  • ✅ CreateChangelog_WithExtractReleaseNotes_LongReleaseNote_UsesAsDescription - Verifies long release notes are used as description
  • ✅ CreateChangelog_WithExtractReleaseNotes_MultiLineReleaseNote_UsesAsDescription - Verifies multi-line release notes are used as description
  • ✅ CreateChangelog_WithExtractReleaseNotes_NoReleaseNote_UsesPrTitle - Verifies fallback to PR title when no release note found
  • ✅ CreateChangelog_WithExtractReleaseNotes_ExplicitTitle_TakesPrecedence - Verifies explicit title takes precedence over extracted release note
  • ✅ CreateChangelog_WithExtractReleaseNotes_ExplicitDescription_TakesPrecedence - Verifies explicit description takes precedence over extracted release note

Total Test Coverage: 23 tests, all passing ✅

Usage Examples

Basic Usage

docs-builder changelog add \
  --prs "https://github.com/elastic/elasticsearch/pull/123456" \
  --products "elasticsearch 9.2.3" \
  --extract-release-notes

Example PR Description Formats

Short Release Note (Used as Title)

## Summary
This PR adds a new feature.

Release Notes: Adds support for new aggregation types

Long Release Note (Used as Description)

## Summary
This PR adds a new feature.

Release Notes: Adds support for new aggregation types including date histogram, range aggregations, and nested aggregations with improved performance

Multi-line Release Note (Used as Description)

## Summary
This PR adds a new feature.

Release Notes: Adds support for new aggregation types
This includes date histogram and range aggregations
with improved performance

Behavior Details

Release Note Extraction Logic

1. HTML Comments: Stripped before extraction to avoid picking up template instructions
2. Format Matching: Case-insensitive matching of various "Release Notes" formats
3. Content Extraction: Extracts content until:
   • Double newline
   • End of string
   • New markdown header

Usage Rules

• Short release notes (≤120 characters, single line):

  • Used as changelog title
  • Only applied if --title is not explicitly provided

• Long release notes (>120 characters or multi-line):

  • Used as changelog description
  • Only applied if --description is not explicitly provided

• No release note found:

  • No changes made to title or description
  • Falls back to standard PR title extraction

• Explicit values take precedence:

  • If --title is provided, extracted release note title is ignored
  • If --description is provided, extracted release note description is ignored

Technical Implementation Notes

Regex Pattern

The extraction uses a compiled regex pattern (via GeneratedRegexAttribute) that matches:

• Start of line with optional markdown headers
• "release note(s)" in various formats (case-insensitive)
• Colon, dash, or whitespace separator
• Content capture (lazy) until terminator

Performance

• Uses GeneratedRegexAttribute for compile-time regex generation
• Efficient HTML comment stripping
• Minimal string allocations

Compatibility

• Works with existing --prs option
• Compatible with --strip-title-prefix option
• Works with single PR and multiple PRs processing
• Respects existing label blockers and configuration

Files Changed

New Files

• src/services/Elastic.Documentation.Services/Changelog/ReleaseNotesExtractor.cs
• tests/Elastic.Documentation.Services.Tests/ReleaseNotesExtractorTests.cs

Modified Files

• src/services/Elastic.Documentation.Services/Changelog/GitHubPrService.cs
• src/services/Elastic.Documentation.Services/Changelog/ChangelogInput.cs
• src/services/Elastic.Documentation.Services/ChangelogService.cs
• src/tooling/docs-builder/Commands/ChangelogCommand.cs
• docs/cli/release/changelog-add.md
• docs/contribute/changelog.md
• tests/Elastic.Documentation.Services.Tests/ChangelogServiceTests.cs

Testing Results

All tests pass successfully:

• ✅ 17 ReleaseNotesExtractor unit tests
• ✅ 6 ChangelogService integration tests
• ✅ Total: 23 tests, 0 failures

Related Issues

This implementation is based on the functionality described in:

• https://github.com/elastic/kibana-release-notes
• https://github.com/elastic/docs-eng-team/issues/370

The extraction logic matches the patterns used in the kibana-release-notes project for consistency across Elastic's documentation tooling.

Examples

Short sentence

./docs-builder changelog add --prs 248804 \
  --repo kibana --owner elastic \
  --products "kibana 9.3.0" \
  --output /path/to/kibana/docs/changelog/ \
  --config /path/to/kibana/docs/changelog.yml \
  --extract-release-notes

The resulting changelog contains this string in the title:

pr: 248804
type: bug-fix
products:
- product: kibana
  target: 9.3.0
areas:
- Kibana platform
title: Fixes an issue with share modal where all time ranges were being shared as absolute.

Paragraph

./docs-builder changelog add \             
  --products "kibana 9.2.0" \
  --output /path/to/kibana/docs/changelog/ \
  --config /path/to/kibana/docs/changelog.yml \
  --extract-release-notes \
  --prs "https://github.com/elastic/kibana/pull/230067, https://github.com/elastic/kibana/pull/235150, https://github.com/elastic/kibana/pull/236903"

The release note blurbs in these cases are added to the changelog descriptions. For example:

pr: https://github.com/elastic/kibana/pull/236903
type: feature
products:
- product: kibana
  target: 9.2.0
areas:
- Platform
title: '[i18n] Integrate 9.0.3 Translations'
description: 'German Locale now available in Kibana. This is the first release of the German locale released under `Beta`. We did improve our testing of the translations quality, but since this is the first release of the German locale we are releasing it under Beta expecting further enhancements in every future release. To get started set the locale in the kibana settings `i18n.locale: de-DE`. If you find any issues please feel free to raise them on github in the Kibana repo.'

Generative AI disclosure

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

• Yes
• No

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