Fix changelog render empty sections

[lcawl]

Overview

As noted in #2568, there is an outstanding issue in the docs-builder changelog render command output where we ought to handle empty sections better.
That is to say, if certain areas are blocked from the output, their section titles should not appear in the output.
Likewise if all content on a page is commented out, a default phrase should be added to avoid blank pages.

I've also merged #2570 into this PR, which improves the render command messages.

Screenshots

Before

When testing with files from elastic/elasticsearch#140795, if changelogs were blocked due to their areas, the area sections still appeared in the output, for example:

Likewise empty sections appeared in the index.md file, for example:

After

With this fix, when all content on a page is blocked, a default phrase is added (and the empty sections' titles are commented out), for example:

... and the empty sections' titles are likewise hidden in the index.md file:

Changes Made

1. Fixed Block Configuration Regression

Problem: Changelog entries were not being commented out based on block > publish configuration in changelog.yml.

Solution:

• Added ChangelogConfiguration to ChangelogRenderContext to pass configuration through the rendering pipeline
• Updated ChangelogRenderUtilities.ShouldHideEntry to check block configuration rules
• Implemented product-specific override logic (product-specific blockers override global blockers)
• Updated all renderers to use the enhanced ShouldHideEntry method

Files Modified:

• src/services/Elastic.Changelog/Rendering/ChangelogRenderContext.cs - Added Configuration property
• src/services/Elastic.Changelog/Rendering/ChangelogRenderingService.cs - Pass configuration to context
• src/services/Elastic.Changelog/Rendering/ChangelogRenderUtilities.cs - Implemented block checking logic
• All Markdown and Asciidoc renderers - Updated to use enhanced ShouldHideEntry

2. Empty Subsection Header Commenting

Feature: When using --subsections option, subsection headers are commented out if all entries within that subsection are blocked.

Implementation:

• Markdown renderers: Use % prefix for regular entries, <!-- --> HTML comments for breaking changes/deprecations/known issues
• Asciidoc renderers: Use // prefix for all subsection headers

Files Modified:

• src/services/Elastic.Changelog/Rendering/Markdown/IndexMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Markdown/BreakingChangesMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Markdown/DeprecationsMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Markdown/KnownIssuesMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Asciidoc/EntriesByAreaAsciidocRenderer.cs
• src/services/Elastic.Changelog/Rendering/Asciidoc/BreakingChangesAsciidocRenderer.cs
• src/services/Elastic.Changelog/Rendering/Asciidoc/DeprecationsAsciidocRenderer.cs
• src/services/Elastic.Changelog/Rendering/Asciidoc/KnownIssuesAsciidocRenderer.cs

3. "No Items" Messages for Empty Pages

Feature: When all entries in a changelog file are blocked, display a descriptive message while keeping the commented-out content.

Behavior:

• All entries are rendered (commented out if blocked)
• A descriptive message is added at the end when all entries are hidden
• The page is never completely empty

Updated Messages:

• Breaking Changes: _There are no breaking changes associated with this release._
• Deprecations: _There are no deprecations associated with this release._
• Known Issues: _There are no known issues associated with this release._
• Index (Features/Fixes): _There are no new features, enhancements, or fixes associated with this release._

Files Modified:

• src/services/Elastic.Changelog/Rendering/Markdown/BreakingChangesMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Markdown/DeprecationsMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Markdown/KnownIssuesMarkdownRenderer.cs
• src/services/Elastic.Changelog/Rendering/Markdown/IndexMarkdownRenderer.cs

4. Comprehensive Test Coverage

Added Tests: Created BlockConfigurationTests.cs with 12 test cases covering:

1. RenderChangelogs_WithBlockedArea_CommentsOutMatchingEntries - Basic blocking by area
2. RenderChangelogs_WithBlockedType_CommentsOutMatchingEntries - Blocking by type
3. RenderChangelogs_WithGlobalBlockedArea_CommentsOutMatchingEntries - Global block configuration
4. RenderChangelogs_WithProductSpecificOverride_OverridesGlobalBlock - Product-specific overrides
5. RenderChangelogs_WithMultipleBlockedAreas_CommentsOutAllMatchingEntries - Multiple blocked areas
6. RenderChangelogs_WithBlockedArea_BreakingChange_UsesBlockComments - Breaking changes use HTML comments
7. RenderChangelogs_WithBlockedArea_KnownIssue_UsesBlockComments - Known issues use HTML comments
8. RenderChangelogs_WithSubsections_CommentsOutEmptySubsectionHeaders - Empty subsection headers are commented
9. RenderChangelogs_WithAllEntriesBlocked_ShowsNoItemsMessage - "No items" message for index.md
10. RenderChangelogs_WithAllBreakingChangesBlocked_ShowsNoBreakingChangesMessage - "No items" message for breaking changes
11. RenderChangelogs_WithAllDeprecationsBlocked_ShowsNoDeprecationsMessage - "No items" message for deprecations
12. RenderChangelogs_WithAllKnownIssuesBlocked_ShowsNoKnownIssuesMessage - "No items" message for known issues

File Created:

• tests/Elastic.Changelog.Tests/Changelogs/Render/BlockConfigurationTests.cs

Technical Details

Block Configuration Logic

The ShouldHideEntry method checks entries in this order:

1. Feature ID blocking (if entry has a feature-id in the hide list)
2. Product-specific block configuration (checks block.product.{productId}.publish)
3. Global block configuration (checks block.publish)

Blocking rules use OR logic:

• If types is specified and entry type matches → block
• If areas is specified and entry has matching area → block

Commenting Syntax

• Markdown regular entries: % prefix for each line
• Markdown breaking changes/deprecations/known issues: <!-- --> HTML comment blocks
• Asciidoc: // prefix for headers and content

Testing

• All 12 block configuration tests pass
• Build succeeds with no errors
• No linting errors

Impact

• Changelog entries are correctly commented out based on changelog.yml configuration
• Empty subsections don't show visible headers
• Pages with all content blocked display helpful messages
• Comprehensive test coverage prevents future regressions

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

[github-actions]

🔍 Preview links for changed docs

• docs/cli/release/changelog-add.md
• docs/cli/release/changelog-render.md