Skip to content

docs: stop prettier table re-alignment churn in expressions.md#4583

Merged
andygrove merged 3 commits into
apache:mainfrom
andygrove:disable-prettier-expressions-md
Jun 3, 2026
Merged

docs: stop prettier table re-alignment churn in expressions.md#4583
andygrove merged 3 commits into
apache:mainfrom
andygrove:disable-prettier-expressions-md

Conversation

@andygrove
Copy link
Copy Markdown
Member

Which issue does this PR close?

N/A. This is a documentation/tooling change to reduce contributor friction.

Rationale for this change

docs/source/user-guide/latest/expressions.md is hand-edited by nearly every PR that adds or updates a Spark expression. The tables are formatted by prettier, which aligns each column to its widest cell. Adding a single row whose Notes (or any) cell is wider than the current column re-pads every other row in that table. The result is large, noisy diffs and frequent merge conflicts between concurrent expression PRs that each touch the same table.

What changes are included in this PR?

  • Add a .prettierignore that exempts docs/source/user-guide/latest/expressions.md. The file is almost entirely tables, and prettier's markdown prose handling is whitespace-only (proseWrap defaults to preserve), so exempting the whole file costs nothing for the surrounding prose while stopping the column re-padding.
  • Collapse the existing table padding to single spaces. With prettier no longer aligning the tables, removing the alignment padding means adding a row never shifts the other rows. Combined with the prettier exemption, every future addition is a true one-line diff that cannot collide on re-alignment. This is a one-time reformat (470 rows) with no content changes.

How are these changes tested?

Verified locally that prettier --check "**/*.md" passes with the file ignored (including after appending a deliberately misaligned row), and that all 20 tables retain consistent column counts after the reformat, with the escaped-pipe cell (`\|` in bitwise_funcs) preserved.

andygrove added 3 commits June 3, 2026 10:58
prettier re-aligns markdown table columns to the widest cell, so adding
a single expression row rewrites every row in the table. That produces
noisy diffs and frequent merge conflicts between PRs that each add new
expressions. Exempt the file from prettier so future additions stay as
one-line diffs.
With prettier no longer aligning the tables, collapse the existing
column padding so that adding an expression row never shifts the other
rows. Combined with the prettier exemption, every future addition is a
true one-line diff that cannot collide on re-alignment.
The Apache RAT license check rejects .prettierignore for missing a
license header, failing the Preflight CI job. Add the standard ASF
header in shell-comment style.
Copy link
Copy Markdown
Contributor

@mbutrovich mbutrovich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @andygrove. So what's the workflow going forward for this file? Run prettier on it at release or something just to get it back into conformity?

@andygrove
Copy link
Copy Markdown
Member Author

Thanks @andygrove. So what's the workflow going forward for this file? Run prettier on it at release or something just to get it back into conformity?

The short term answer:

  • Viewing this in GitHub renders just fine and viewing source is arguable more readable than having everything padded
  • This markdown gets published as HTML here and the prettier formatting doesn't impact this
  • Yes, as part of the release process we do generate docs (i.e. compat guide) and run prettier so this would be prettified in release branches but not in main
  • I guess the question is, do we care that the version in main is not prettified?

The long term answer:

@andygrove andygrove merged commit 441d29f into apache:main Jun 3, 2026
15 checks passed
@andygrove andygrove deleted the disable-prettier-expressions-md branch June 3, 2026 19:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants