Problem
The project uses black for formatting and ruff for linting, but this isn't
explicit anywhere. Both tools are in dev dependencies, and ruff format --check
reports 22 files diverging from ruff's formatting opinions — even though black
(the actual project formatter) is happy with all files.
This ambiguity could lead a new contributor to run ruff format instead of
black, introducing unnecessary churn.
Proposal
- Document explicitly that black is the formatter, ruff is the linter
- Add a
[tool.ruff.format] section or comment in pyproject.toml clarifying
that ruff format is not used
- Ensure the CI doctrine job uses
uv run consistently (it currently calls
pytest directly, which can pick up the wrong Python)
Why black over ruff format
- Michael is actively using black — match the workflow of the person writing code
- black is PSF-ecosystem, maintained by CPython core developers
- ruff format has minor opinion divergences from black that cause false alarms
- Speed difference is irrelevant at this codebase size
- Keeps ruff focused on what it's best at: fast linting
Closes #126
Problem
The project uses black for formatting and ruff for linting, but this isn't
explicit anywhere. Both tools are in dev dependencies, and
ruff format --checkreports 22 files diverging from ruff's formatting opinions — even though black
(the actual project formatter) is happy with all files.
This ambiguity could lead a new contributor to run
ruff formatinstead ofblack, introducing unnecessary churn.Proposal
[tool.ruff.format]section or comment inpyproject.tomlclarifyingthat ruff format is not used
uv runconsistently (it currently callspytestdirectly, which can pick up the wrong Python)Why black over ruff format
Closes #126