[
https://issues.apache.org/jira/browse/KAFKA-21205?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Edmond Abraham reassigned KAFKA-21205:
--------------------------------------
Assignee: Edmond Abraham
> PR linter corrupts Markdown lists and fenced code blocks when rewriting
> descriptions
> ------------------------------------------------------------------------------------
>
> Key: KAFKA-21205
> URL: https://issues.apache.org/jira/browse/KAFKA-21205
> Project: Kafka
> Issue Type: Bug
> Components: build
> Environment: apache/kafka GitHub Actions PR workflows targeting
> trunk. Formatter verified at ef5c8dc99503176e0d7f5eb5068372d12f04d9df. This
> affects repository contribution tooling, not Kafka broker runtime.
> Reporter: Denis Coric
> Assignee: Edmond Abraham
> Priority: Minor
>
> h3. Problem
> The Pull Request Linter rewrites PR descriptions with
> textwrap.fill(width=72), but its Markdown detection does not preserve valid
> indented lists or fenced code blocks. Editing the description to repair the
> formatting triggers the workflow again, so contributors repeatedly lose their
> formatting.
> h3. Reproduction
> On an open PR targeting trunk where the PR workflows can run:
> # Put the following Markdown in the PR description. Each bullet starts with
> one space.
> # Save the description and let Pull Request Reviewed and then Pull Request
> Linter complete.
> # Inspect the description edit history and raw Markdown.
> Input:
> {noformat}
> Example list:
> - first item
> - second item
> {noformat}
> Actual output:
> {noformat}
> Example list: - first item - second item
> {noformat}
> A second example demonstrates that a fenced code block is not a reliable
> workaround. Input:
> {noformat}
> ```
> first command
> second command
> third command
> ```
> {noformat}
> Actual output:
> {noformat}
> ```
> first command
> second command third command
> ```
> {noformat}
> Both transformations were reproduced locally using the unmodified
> split_paragraphs function and formatting loop extracted from
> .github/scripts/pr-format.py at revision
> ef5c8dc99503176e0d7f5eb5068372d12f04d9df. Only the formatting logic was
> executed, without invoking the script's GitHub write path.
> h3. Expected behavior
> Linting or wrapping prose should preserve Markdown structure: list items and
> nesting must remain intact, and code block contents, indentation, line breaks
> and blank lines must remain unchanged. Subsequent linter runs should preserve
> these properties.
> h3. Cause
> *
> [pr-format.py|https://github.com/apache/kafka/blob/ef5c8dc99503176e0d7f5eb5068372d12f04d9df/.github/scripts/pr-format.py]
> checks line[0] for Markdown markers. A leading space means an indented list
> can be classified as prose, then joined and rewrapped.
> * The Markdown flag resets at blank lines without tracking whether the parser
> is inside a fenced code block. Consequently, interior code paragraphs can be
> treated as prose. Even paragraphs recognized as Markdown have each line
> passed through textwrap.fill.
> * The script writes the result back using gh pr edit --body-file.
> *
> [pr-reviewed.yml|https://github.com/apache/kafka/blob/ef5c8dc99503176e0d7f5eb5068372d12f04d9df/.github/workflows/pr-reviewed.yml]
> runs on PR edits, and
> [pr-linter.yml|https://github.com/apache/kafka/blob/ef5c8dc99503176e0d7f5eb5068372d12f04d9df/.github/workflows/pr-linter.yml]
> invokes the formatter when that workflow succeeds.
> h3. Related work and possible resolution
> KAFKA-19013 introduced the intended 72-column preformatting behavior through
> [PR #19242|https://github.com/apache/kafka/pull/19242]. This report concerns
> corruption of Markdown by that behavior.
> Consider separating validation from description mutation, or limiting
> wrapping to prose using Markdown-aware parsing. Regression coverage should
> include indented and nested lists, fenced code blocks containing blank lines
> and long lines, and repeated formatting of the same input.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
