Skip to content

Improve changelog render for asciidoc#3262

Merged
cotti merged 2 commits intochangelog-render-dropdownsfrom
changelog-render-asciidoc
May 7, 2026
Merged

Improve changelog render for asciidoc#3262
cotti merged 2 commits intochangelog-render-dropdownsfrom
changelog-render-asciidoc

Conversation

@lcawl
Copy link
Copy Markdown
Contributor

@lcawl lcawl commented May 7, 2026

This PR builds on #3244 (and addresses #3244 (comment)).

It fixes formatting issues that were apparent while testing the docs-builder changelog render command with --format-type asciidoc. For example:

  • No list continuation: Multi-block list items (description + Impact + Action) don't use + continuation syntax
  • Wrong strong formatting: used Impact: and Action: instead of idiomatic Impact:
  • Broken list structure: Additional paragraphs terminate the list item instead of continuing it
  • Inconsistent subsections handling: Some renderers ignore the --subsections flag and always add "General::" headers
  • Definition lists break list continuation: AsciiDoc definition list syntax (General::) doesn't work with list continuation markers (+)

Screenshots

Before

  • Lists with paragraphs and no --subsections aren't aligned well and inject an unexpected "general" area:
    image

  • Lists with paragraphs and --subsections are smushed together in definition lists
    image

After

  • Lists with paragraphs and no --subsections work:
    image

  • Lists with paragraphs and --subsections work by moving away from fragile definition lists:
    image

NOTE: Since there are teams who have already said they don't want the descriptions published, I've created #3263 as a follow-on too.

AI Summary

Improves changelog render AsciiDoc output for multi-block list items (description, Impact, Action), aligns Markdown PR/issue link rendering with analyzer-friendly options, fixes AsciiDoc subsection behavior versus --subsections, replaces definition lists with nested sections where grouping is intended, and documents AsciiDoc behavior in the CLI reference.

AsciiDoc

  • AsciidocRendererBase
    • Emits list continuation (+) before description text (when continuation applies) and before Impact/Action blocks so bullets stay attached to the list item.
    • Drops two-space indentation of full description blobs; emits the raw description (hidden entries still prefixed with // per line).
    • Uses constrained bold *Impact:* / *Action:* instead of **Impact:** / **Action:**.
  • Section / grouping (975b4200)
    • Deprecations, Known Issues, Highlights, Entries-by-area: respect Subsections; when --subsections is off, collapse to a single group without a General-style wrapper.
    • When --subsections is on, replace Component:: definition lists with [float] + ==== Title nested sections (and commented-out equivalents when all entries in the group are hidden).
    • Breaking changes: subtype headers use the same nested-section style instead of bold-only lines; hidden groups get commented // [float] / // ==== ….
  • CA1305 / globalization: interpolated section titles use AppendLine(CultureInfo.InvariantCulture, …) where applicable (per second commit diff).

Markdown

  • Introduces PrIssueLinkOptions and a single RenderPrIssueLinks(StringBuilder, PrIssueLinkOptions) API (avoids long parameter lists / adjacent booleans).
  • Call sites updated in breaking changes, deprecations, known issues, and highlights renderers.

Docs & tests

  • docs/cli/changelog/render.md: clarifies that AsciiDoc ignores --dropdowns, and briefly describes list continuation, *Impact:* / *Action:*, and attachment of blocks to list items.
  • DropdownRenderTests: AsciiDoc expectations updated for *Impact:* / *Action:*.

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-2, claude-4-sonnet-thinking

@lcawl lcawl added the fix label May 7, 2026
@lcawl lcawl marked this pull request as ready for review May 7, 2026 02:20
@lcawl lcawl requested review from a team as code owners May 7, 2026 02:20
@lcawl lcawl requested a review from reakaleek May 7, 2026 02:20
@cotti cotti merged commit aa32ca1 into changelog-render-dropdowns May 7, 2026
22 checks passed
@cotti cotti deleted the changelog-render-asciidoc branch May 7, 2026 15:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants