Skip to content

Conversation

@lcawl
Copy link
Contributor

@lcawl lcawl commented Jan 27, 2026

This PR builds on top of the changes in #2569

Per Block creation or publishing "When you run the docs-builder changelog render command, changelog entries that match the specified products and areas or types are commented out of the documentation output files. The command will emit warnings indicating which changelog entries were commented out and why."

Those messages seem to have disappeared in recent refactorings, however.
I suspect this was not intentional, so this PR re-adds and improves them (to mention the PR number if possible).
If it was intentional and they're being logged somewhere else, that's fine as long as they are actionable.

Summary of Changes

Enhanced Warning Messages for Blocked Changelog Entries

Changes to ChangelogRenderingService.cs

  1. Added GetEntryIdentifier:

    • Prefers PR numbers over entry titles in warning messages
    • Extracts PR number from the entry's PR URL using ChangelogTextUtilities.ExtractPrNumber
    • Uses the entry-specific repository from context.EntryToRepo, falling back to context.Repo
    • Returns "for PR {number}" if a PR number is found, otherwise "'{title}'"
  2. Updated warning message format:

    • Changed from: "Changelog entry '{entry.Title}' will be commented out..."
    • Changed to: "Changelog entry {entryIdentifier} will be commented out..."
    • Examples:
      • "Changelog entry for PR 100 will be commented out because it matches block configuration: area 'Allocation'"
      • "Changelog entry 'Blocked Allocation feature' will be commented out because it matches block configuration: area 'Allocation'" (fallback when no PR)

Changes to BlockConfigurationTests.cs

  1. Fixed namespace reference:
    • Changed from: Elastic.Documentation.Diagnostics.Severity.Warning
    • Changed to: Documentation.Diagnostics.Severity.Warning
    • Resolves a namespace issue in the test assertions

Benefits

  • More actionable warnings: PR numbers are easier to reference than titles
  • Cleaner output: avoids duplicate warnings for entries hidden by multiple mechanisms
  • Better traceability: PR numbers link directly to the source PR
  • Backward compatible: falls back to entry title when PR number is unavailable

Testing

  • All existing tests pass
  • The RenderChangelogs_WithBlockedEntries_EmitsWarnings test verifies warnings are emitted correctly
  • Warning messages now use PR numbers when available, improving clarity

Examples

When testing a Cloud Serverless variation of the files in elastic/elasticsearch#140795, the changelog render command now outputs messages like this:

...
	The following errors and warnings were found in the documentation

Warning: Changelog entry for PR 140199 will be commented out because it matches block configuration: area 'Allocation'
 
Warning: Changelog entry for PR 136066 will be commented out because it matches block configuration: area 'Allocation'
 
Warning: Changelog entry for PR 138541 will be commented out because it matches block configuration: area 'Codec'

... 

Warning: Changelog entry for PR 138515 will be commented out because it matches block configuration: area 'Codec'

	0 Errors / 39 Warnings / 0 Hints

Generative AI disclosure

  1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?
  • Yes
  • No
  1. 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

@lcawl lcawl marked this pull request as ready for review January 27, 2026 00:19
@lcawl lcawl requested a review from a team as a code owner January 27, 2026 00:19
@lcawl lcawl requested a review from Mpdreamz January 27, 2026 00:19
@lcawl lcawl merged commit 6a25085 into changelog-render-cleanup Jan 27, 2026
23 of 25 checks passed
@lcawl lcawl deleted the changelog-render-messages branch January 27, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants