Skip to content

Standardise on black for formatting, ruff for linting #126

@monkeypants

Description

@monkeypants

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions