Skip to content

Keep the ruff formatter out of Markdown - #4

Merged
asg017 merged 1 commit into
load-prettier-svelte-pluginfrom
keep-ruff-out-of-markdown
Sep 25, 2026
Merged

asg017 merged 1 commit into
load-prettier-svelte-pluginfrom
keep-ruff-out-of-markdown

Conversation

@asg017

@asg017 asg017 commented Sep 17, 2026

Copy link
Copy Markdown
Collaborator
🤖 Claude-generated PR description

Stacked on #3.

ruff 0.16 began formatting Python code blocks inside .md files. That makes
uv run ruff format --check want to rewrite README's samples, so
just format-check fails:

1 file would be reformatted, 38 files already formatted

The one file is README.md. Every actual .py file is clean (32 files already formatted).

This has to be settled before CI runs format-check, which the next PR adds.

Why this was invisible

uv.lock is git-ignored (.gitignore:13) and pyproject.toml only floors
ruff at >=0.15.0. So a fresh resolve — CI, or any new checkout — gets 0.16.x,
while an older cached environment stays on 0.15.x, which never looked at .md at
all.

I had 0.15.8 locally and reported format-check green. Three worktrees with fresh
venvs all resolved 0.16.8 and disagreed. This fix is verified against 0.16.8,
not the stale environment.

ruff just format-backend-check
0.15.8 (stale cache) 36 files, clean — never reads .md
0.16.8 (fresh resolve = CI) README.md would be reformatted

Why exclude rather than reformat

The reformat is not an improvement:

  • README aligns trailing comments so a block of schedule examples reads as a
    column; ruff flattens each to a single space.
  • Several samples are deliberately partial.
  • PR 12 owns the README, and one of the hunks ruff wants is the
    scheduler.update_task sample that PR 3 deletes outright — so formatting
    it now is churn with a short life.

Excluding Markdown is also stable where reformatting is not: it holds across
future ruff releases instead of re-churning README whenever the embedded-code
formatter changes.

Checked that the rewrites all land at lines 27–150, outside the
telemetry-reference generated region (338–411), so telemetry-doc-check was
never actually at risk either way.

Scope

Scoped to [tool.ruff.format] rather than a global exclude, so linting is
unaffected. This repo only ever runs ruff format — ruff check is not wired
into any recipe.

Verification

Under ruff 0.16.8:

Check Result
just format-check GREEN (was RED on README.md)
just types-check-fresh GREEN
just telemetry-doc-check GREEN
just test 171, unchanged

Follow-up worth a decision

uv.lock being git-ignored means Python dependency versions are not
reproducible
between a developer's checkout and CI — this ruff skew is one
symptom, and it cost a wrong green here. Whether to start committing the
lockfile is a separate call; filed as its own ticket rather than folded in.

🤖 Generated with Claude Code

ruff 0.16 began formatting Python code blocks inside .md files. That makes
`uv run ruff format --check` want to rewrite README's samples, so
`just format-check` fails on README.md with "1 file would be reformatted,
38 files already formatted" while every actual .py file is clean.

This has to be settled before CI runs format-check, which the next PR adds.

The reformat is not an improvement. README aligns trailing comments so a block
of schedule examples reads as a column, and ruff flattens each to a single
space. Several samples are deliberately partial. Documentation prose and its
snippets are a human's call, not the formatter's, and PR 12 owns the README
anyway -- one of the hunks ruff wants is the `scheduler.update_task` sample
that PR 3 deletes outright, so formatting it now is churn with a short life.

Excluding Markdown is also stable, where reformatting is not: it holds across
future ruff releases instead of re-churning README whenever the embedded-code
formatter changes.

Scoped to [tool.ruff.format] rather than a global exclude, so linting is
unaffected. (This repo only ever runs `ruff format`; `ruff check` is not wired
into any recipe.)

Why this was invisible until now: uv.lock is git-ignored and pyproject only
floors ruff at >=0.15.0. A fresh resolve -- CI, or any new checkout -- gets
0.16.x, while an older cached environment stays on 0.15.x, which never looked
at .md at all. I had 0.15.8 locally and reported format-check green; three
worktrees with fresh venvs all resolved 0.16.8 and disagreed. Verified this fix
against 0.16.8, not the stale environment.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@asg017
asg017 force-pushed the keep-ruff-out-of-markdown branch from 90ce00f to 7d7d887 Compare September 25, 2026 17:30
@asg017
asg017 added this pull request to stack #19 September 25, 2026 18:17
@asg017
asg017 merged commit 40066b0 into main Sep 25, 2026
15 checks passed
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.

1 participant