Add --extract-release-notes to changelog add (#2483)

Author: lcawl

docs/cli/release/changelog-add.md

@@ -65,6 +65,19 @@ docs-builder changelog add [options...] [-h|--help]
 :   For example, if a PR title is `"[Attack discovery] Improves Attack discovery hallucination detection"`, the changelog title will be `"Improves Attack discovery hallucination detection"`.
 :   This option applies only when the title is derived from the PR (when `--title` is not explicitly provided).
 
+`--extract-release-notes`
+:   Optional: When used with `--prs`, extract release notes from PR descriptions and use them in the changelog.
+:   The extractor looks for content in various formats in the PR description:
+:   - `Release Notes: ...`
+:   - `Release-Notes: ...`
+:   - `release notes: ...`
+:   - `Release Note: ...`
+:   - `Release Notes - ...`
+:   - `## Release Note` (as a markdown header)
+:   Short release notes (≤120 characters, single line) are used as the changelog title (only if `--title` is not explicitly provided).
+:   Long release notes (>120 characters or multi-line) are used as the changelog description (only if `--description` is not explicitly provided).
+:   If no release note is found, no changes are made to the title or description.
+
 `--subtype <string?>`
 :   Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`).
 :   The valid subtypes are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).

docs/contribute/changelog.md

@@ -141,6 +141,7 @@ Options:
   --config <string?>                Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' [Default: null]
   --use-pr-number                   Optional: Use the PR number as the filename instead of generating it from a unique ID and title
   --strip-title-prefix              Optional: When used with --prs, remove square brackets and text within them from the beginning of PR titles
+  --extract-release-notes           Optional: When used with --prs, extract release notes from PR descriptions. Short release notes (≤120 characters, single line) are used as the title, long release notes (>120 characters or multi-line) are used as the description. Looks for content in formats like "Release Notes: ...", "Release-Notes: ...", "## Release Note", etc.
 ```
 
 ### Authorization
@@ -255,6 +256,29 @@ The `--strip-title-prefix` option in this example means that if the PR title has
 The `--strip-title-prefix` option only applies when the title is derived from the PR (when `--title` is not explicitly provided). If you specify `--title` explicitly, that title is used as-is without any prefix stripping.
 :::
 
+#### Extract release notes from PR descriptions [example-extract-release-notes]
+
+When you use the `--prs` option, you can also add the `--extract-release-notes` option to automatically extract text from the PR descriptions and use them in your changelog.
+
+In particular, it looks for content in these formats in the PR description:
+
+- `Release Notes: This is the extracted sentence.`
+- `Release-Notes: This is the extracted sentence.`
+- `release notes: This is the extracted sentence.`
+- `Release Note: This is the extracted sentence.`
+- `Release Notes - This is the extracted sentence.`
+- `## Release Note` (as a markdown header)
+
+The extracted content is handled differently based on its length:
+
+- **Short release notes (≤120 characters, single line)**: Used as the changelog title (only if `--title` is not explicitly provided)
+- **Long release notes (>120 characters or multi-line)**: Used as the changelog description (only if `--description` is not explicitly provided)
+- **No release note found**: No changes are made to the title or description
+
+:::{note}
+If you explicitly provide `--title` or `--description`, those values take precedence over extracted release notes.
+:::
+
 #### Block changelog creation with PR labels [example-block-label]
 
 You can configure product-specific label blockers to prevent changelog creation for certain PRs based on their labels.

src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs

@@ -720,16 +720,25 @@ public class LlmDefinitionItemRenderer : MarkdownObjectRenderer<LlmMarkdownRende
 {
 	protected override void Write(LlmMarkdownRenderer renderer, DefinitionItem obj)
 	{
-		var first = obj.Cast<LeafBlock>().First();
 		renderer.EnsureBlockSpacing();
+
+		// Render the term (first element) if it's a LeafBlock
+		var first = obj.FirstOrDefault();
+		var hasTermBlock = first is LeafBlock;
+
 		renderer.Write("<definition");
-		renderer.Write(" term=\"");
-		renderer.Write(GetPlainTextFromLeafBlock(renderer, first));
-		renderer.WriteLine("\">");
-		for (var index = 0; index < obj.Count; index++)
+		if (hasTermBlock)
+		{
+			renderer.Write(" term=\"");
+			renderer.Write(GetPlainTextFromLeafBlock(renderer, (LeafBlock)first!));
+			renderer.Write("\"");
+		}
+		renderer.WriteLine(">");
+
+		// Render the definitions (remaining elements, or all if no term block)
+		var startIndex = hasTermBlock ? 1 : 0;
+		for (var index = startIndex; index < obj.Count; index++)
 		{
-			if (index == 0)
-				continue;
 			var block = obj[index];
 			LlmRenderingHelpers.RenderBlockWithIndentation(renderer, block);
 		}

src/services/Elastic.Documentation.Services/Changelog/ChangelogInput.cs

@@ -27,5 +27,6 @@ public class ChangelogInput
 	public string? Config { get; set; }
 	public bool UsePrNumber { get; set; }
 	public bool StripTitlePrefix { get; set; }
+	public bool ExtractReleaseNotes { get; set; }
 }
 

src/services/Elastic.Documentation.Services/Changelog/GitHubPrService.cs

@@ -71,6 +71,7 @@ static GitHubPrService()
 			return new GitHubPrInfo
 			{
 				Title = prData.Title,
+				Body = prData.Body ?? string.Empty,
 				Labels = prData.Labels?.Select(l => l.Name).ToArray() ?? []
 			};
 		}
@@ -140,6 +141,7 @@ private static (string? owner, string? repo, int? prNumber) ParsePrUrl(string pr
 	private sealed class GitHubPrResponse
 	{
 		public string Title { get; set; } = string.Empty;
+		public string Body { get; set; } = string.Empty;
 		public List<GitHubLabel>? Labels { get; set; }
 	}
 
@@ -161,6 +163,7 @@ private sealed partial class GitHubPrJsonContext : JsonSerializerContext;
 public class GitHubPrInfo
 {
 	public string Title { get; set; } = string.Empty;
+	public string Body { get; set; } = string.Empty;
 	public string[] Labels { get; set; } = [];
 }
 

src/services/Elastic.Documentation.Services/Changelog/ReleaseNotesExtractor.cs

@@ -0,0 +1,112 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Text.RegularExpressions;
+
+namespace Elastic.Documentation.Services.Changelog;
+
+/// <summary>
+/// Utility class for extracting release notes from PR descriptions
+/// </summary>
+public static partial class ReleaseNotesExtractor
+{
+	[GeneratedRegex(@"<!--[\s\S]*?-->", RegexOptions.None)]
+	private static partial Regex HtmlCommentRegex();
+
+	[GeneratedRegex(@"(\r?\n){3,}", RegexOptions.None)]
+	private static partial Regex MultipleNewlinesRegex();
+
+	[GeneratedRegex(@"(?:\n|^)\s*#*\s*release[\s-]?notes?[:\s-]*(.*?)(?:(\r?\n|\r){2}|$|((\r?\n|\r)\s*#+))", RegexOptions.IgnoreCase | RegexOptions.Singleline)]
+	private static partial Regex ReleaseNoteRegex();
+
+	private const int MaxReleaseNoteTitleLength = 120;
+
+	/// <summary>
+	/// Strips HTML comments from markdown text.
+	/// This handles both single-line and multi-line comments.
+	/// Also collapses excessive blank lines that may result from comment removal,
+	/// to prevent creating artificial section breaks.
+	/// </summary>
+	private static string StripHtmlComments(string markdown)
+	{
+		if (string.IsNullOrWhiteSpace(markdown))
+		{
+			return markdown;
+		}
+
+		// Remove HTML comments
+		var withoutComments = HtmlCommentRegex().Replace(markdown, string.Empty);
+
+		// Collapse 3+ consecutive newlines into 2 (preserving paragraph breaks but not creating extra ones)
+		var normalized = MultipleNewlinesRegex().Replace(withoutComments, "\n\n");
+
+		return normalized;
+	}
+
+	/// <summary>
+	/// Finds and retrieves the actual "release note" details from a PR description (in markdown format).
+	/// It will look for:
+	/// - paragraphs beginning with "release note" (or slight variations of that) and the sentence till the end of line.
+	/// - markdown headers like "## Release Note"
+	///
+	/// HTML comments are stripped before extraction to avoid picking up template instructions.
+	/// </summary>
+	/// <param name="markdown">The PR description body</param>
+	/// <returns>The extracted release note content, or null if not found</returns>
+	public static string? FindReleaseNote(string? markdown)
+	{
+		if (string.IsNullOrWhiteSpace(markdown))
+		{
+			return null;
+		}
+
+		// Strip HTML comments first to avoid extracting template instructions
+		var cleanedMarkdown = StripHtmlComments(markdown);
+
+		// Regex breakdown:
+		// - (?:\n|^)\s*#*\s* - start of line, optional whitespace and markdown headers
+		// - release[\s-]?notes? - matches "release note", "release notes", "release-note", "release-notes", etc.
+		// - [:\s-]* - matches separator after "release note" (colon, dash, whitespace) but NOT other non-word chars like {
+		// - (.*?) - lazily capture the release note content
+		// - Terminator: double newline, end of string, or new markdown header
+		var match = ReleaseNoteRegex().Match(cleanedMarkdown);
+
+		if (match.Success && match.Groups.Count > 1)
+		{
+			var releaseNote = match.Groups[1].Value.Trim();
+			return string.IsNullOrWhiteSpace(releaseNote) ? null : releaseNote;
+		}
+
+		return null;
+	}
+
+	/// <summary>
+	/// Extracts release notes from PR body and determines how to use them.
+	/// </summary>
+	/// <param name="prBody">The PR description body</param>
+	/// <returns>
+	/// A tuple where:
+	/// - Item1: The title to use (either original title or extracted release note if short)
+	/// - Item2: The description to use (extracted release note if long, otherwise null)
+	/// </returns>
+	public static (string? title, string? description) ExtractReleaseNotes(string? prBody)
+	{
+		var releaseNote = FindReleaseNote(prBody);
+
+		// No release note found: return nulls (use defaults)
+		if (string.IsNullOrWhiteSpace(releaseNote))
+		{
+			return (null, null);
+		}
+
+		// Long release note (>120 characters or multi-line): use in description
+		if (releaseNote.Length > MaxReleaseNoteTitleLength || releaseNote.Contains('\n'))
+		{
+			return (null, releaseNote);
+		}
+
+		// Short release note (≤120 characters, single line): use in title
+		return (releaseNote, null);
+	}
+}

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

@@ -147,7 +147,8 @@ Cancel ctx
 				Output = input.Output,
 				Config = input.Config,
 				UsePrNumber = input.UsePrNumber,
-				StripTitlePrefix = input.StripTitlePrefix
+				StripTitlePrefix = input.StripTitlePrefix,
+				ExtractReleaseNotes = input.ExtractReleaseNotes
 			};
 
 			// Process this PR (treat as single PR)
@@ -238,6 +239,26 @@ Cancel ctx
 					return true;
 				}
 
+				// Extract release notes from PR body if requested
+				if (input.ExtractReleaseNotes)
+				{
+					var (releaseNoteTitle, releaseNoteDescription) = ReleaseNotesExtractor.ExtractReleaseNotes(prInfo.Body);
+
+					// Use short release note as title if title was not explicitly provided
+					if (releaseNoteTitle != null && string.IsNullOrWhiteSpace(input.Title))
+					{
+						input.Title = releaseNoteTitle;
+						_logger.LogInformation("Using extracted release note as title: {Title}", input.Title);
+					}
+
+					// Use long release note as description if description was not explicitly provided
+					if (releaseNoteDescription != null && string.IsNullOrWhiteSpace(input.Description))
+					{
+						input.Description = releaseNoteDescription;
+						_logger.LogInformation("Using extracted release note as description (length: {Length} characters)", releaseNoteDescription.Length);
+					}
+				}
+
 				// Use PR title if title was not explicitly provided
 				if (string.IsNullOrWhiteSpace(input.Title))
 				{

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

@@ -52,6 +52,7 @@ public Task<int> Default()
 	/// <param name="config">Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml'</param>
 	/// <param name="usePrNumber">Optional: Use the PR number as the filename instead of generating it from a unique ID and title</param>
 	/// <param name="stripTitlePrefix">Optional: When used with --prs, remove square brackets and text within them from the beginning of PR titles (e.g., "[Inference API] Title" becomes "Title")</param>
+	/// <param name="extractReleaseNotes">Optional: When used with --prs, extract release notes from PR descriptions. Short release notes (≤120 characters, single line) are used as the title, long release notes (>120 characters or multi-line) are used as the description. Looks for content in formats like "Release Notes: ...", "Release-Notes: ...", "## Release Note", etc.</param>
 	/// <param name="ctx"></param>
 	[Command("add")]
 	public async Task<int> Create(
@@ -73,6 +74,7 @@ public async Task<int> Create(
 		string? config = null,
 		bool usePrNumber = false,
 		bool stripTitlePrefix = false,
+		bool extractReleaseNotes = false,
 		Cancel ctx = default
 	)
 	{
@@ -139,7 +141,8 @@ public async Task<int> Create(
 			Output = output,
 			Config = config,
 			UsePrNumber = usePrNumber,
-			StripTitlePrefix = stripTitlePrefix
+			StripTitlePrefix = stripTitlePrefix,
+			ExtractReleaseNotes = extractReleaseNotes
 		};
 
 		serviceInvoker.AddCommand(service, input,