Repository navigation
Keep the ruff formatter out of Markdown - #4
Merged
Merged
Conversation
This was referenced Sep 17, 2026
asg017
force-pushed
the
keep-ruff-out-of-markdown
branch
from
September 25, 2026 16:53
031597b to
90ce00f
Compare
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
force-pushed
the
keep-ruff-out-of-markdown
branch
from
September 25, 2026 17:30
90ce00f to
7d7d887
Compare
This was referenced Sep 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🤖 Claude-generated PR description
Stacked on #3.
ruff 0.16 began formatting Python code blocks inside
.mdfiles. That makesuv run ruff format --checkwant to rewrite README's samples, sojust format-checkfails:The one file is
README.md. Every actual.pyfile 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.lockis git-ignored (.gitignore:13) andpyproject.tomlonly floorsruff 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
.mdatall.
I had 0.15.8 locally and reported
format-checkgreen. Three worktrees with freshvenvs all resolved 0.16.8 and disagreed. This fix is verified against 0.16.8,
not the stale environment.
just format-backend-check.mdWhy exclude rather than reformat
The reformat is not an improvement:
column; ruff flattens each to a single space.
scheduler.update_tasksample that PR 3 deletes outright — so formattingit 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-referencegenerated region (338–411), sotelemetry-doc-checkwasnever actually at risk either way.
Scope
Scoped to
[tool.ruff.format]rather than a global exclude, so linting isunaffected. This repo only ever runs
ruff format—ruff checkis not wiredinto any recipe.
Verification
Under ruff 0.16.8:
just format-checkjust types-check-freshjust telemetry-doc-checkjust testFollow-up worth a decision
uv.lockbeing git-ignored means Python dependency versions are notreproducible 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