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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions