Denis Coric created KAFKA-21205:
-----------------------------------
Summary: 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
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)
