Skip to content

[TASK] Clarify black formatting guidance in CONTRIBUTING.md #706

@sergio-sisternes-epam

Description

@sergio-sisternes-epam

Problem

The CONTRIBUTING.md guide references black as a formatting tool, but black is not enforced in CI. When contributors follow the guide and run uv run black ., they get 308 files reformatted -- leading to confusion about whether to include formatting changes in their PRs.

This was flagged by @jacobokeeffe-ow in #688:

When I run uv run black . I end up with 308 files reformatted. I followed the instructions in the contributing guide and don't see anything obvious I'm doing wrong.

Proposed Resolution

Pick one of:

  1. Remove black from the contributing guide -- if we don't enforce it, don't recommend it. Contributors should follow the existing code style in each file.
  2. Add black to CI -- enforce it and do a one-time repo-wide reformat. This is a larger change but establishes a clear standard.
  3. Clarify scope -- update the guide to say "format only the files you touch" and note that black is not enforced in CI.

Impact

Contributor confusion and unnecessary formatting noise in PRs. Low severity but affects contributor experience.

Metadata

Metadata

Assignees

No one assigned

    Labels

    acceptedDirection approved, safe to start workdocumentationImprovements or additions to documentation

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions