Align CONTRIBUTING, Python formatting (Black/isort), and CI

[dmartinol]

Context

CONTRIBUTING recommends uv run black . and uv run isort ., but the repo is not fully formatted to that baseline, so those commands produce large, unrelated diffs. CI does not run Black or isort, so drift is easy to miss.

Goal

Make docs, repo state, and automation agree so contributors know what to run and PRs stay reviewable.

Proposed work

1. CONTRIBUTING — Document the intended workflow: either a one-time full-tree format + “keep it green,” or “format only files you change” until a dedicated formatting PR lands. Note that Black should not be applied to Markdown.
2. Optional formatting PR — Single change-set that runs Black/isort across the agreed Python paths so black . / isort . stop exploding diffs.
3. Pre-commit — Black + isort (check-only or auto-format, per team preference) so local commits match project rules.
4. CI — Same rules as pre-commit (e.g. black --check, isort --check-only) in PR workflows, aligned with Python version / Black target (e.g. match ci.yml).

Success criteria

• CONTRIBUTING matches what maintainers expect and what CI enforces
• Pre-commit and CI use the same formatter config
• (If chosen) main is formatted so repo-wide format commands are low-noise

[github-actions]

Triage decision

accept

Proposed labels

area/ci-cd
area/testing
type/refactor
status/accepted
good first issue

Milestone

0.9.4

Suggested next action

Choose path A (format codebase once with uv run black . && uv run isort . and add a CI lint check) or path B (remove the Black/isort recommendation from CONTRIBUTING.md), then open a PR implementing exactly one of them.

Suggested issue comment

Welcome, and thank you for catching this -- a CONTRIBUTING guide that generates large unexpected diffs for new contributors is a real friction point in the contributor funnel.

There are two clean paths forward:

**Path A (recommended):** Format the entire codebase once (`uv run black . && uv run isort .`), commit it as a single "apply formatter baseline" commit, then add a `black --check` + `isort --check` step to CI. Future PRs auto-fail if they introduce drift. This is the standard approach for Python OSS projects.

**Path B:** Remove the Black/isort recommendation from CONTRIBUTING.md and standardize on the existing code style without a formatter enforced in CI. Lower maintenance overhead, but the code style remains inconsistent over time.

The maintainers lean toward Path A -- it brings CONTRIBUTING, repo state, and automation into full agreement, and it's the pattern contributors expect from a modern Python project. But we want to confirm the choice before you start.

If you're happy to take this on: start with a `git config core.whitespace` check (some files may have mixed line endings on Windows) before running the formatter, and keep the formatting commit separate from any functional changes so the diff is reviewable. Happy to review!

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The contributor task is "follow CONTRIBUTING and send a clean PR." Currently, following CONTRIBUTING produces a massive unrelated formatting diff that blocks the PR or forces the contributor to understand the full project's formatting history. This is a textbook contributor funnel failure. The fix (format baseline + CI enforcement) restores the "contributing is frictionless" promise. good first issue is appropriate because path A is mechanical and well-scoped.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. Adding a code formatter to CI is a development tooling change with no supply chain surface. No theme/security required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author's author_association is NONE -- first-time or low-interaction contributor who has done the research (identifies both the CONTRIBUTING guidance and the CI gap). Reply is warm, presents two concrete paths, and states a preference (Path A) so the author is not stuck in analysis paralysis. The good first issue label signals that this is a welcoming entry point.

Python Architect -- Architecture Reviewer

Not activated -- this is a tooling/CI alignment task. Adding Black/isort to CI is pyproject.toml configuration plus a workflow step. No architectural design required.

Doc Writer -- Documentation Reviewer

CONTRIBUTING.md needs updating: either the Black/isort section is confirmed and supplemented with the CI check note, or it is removed. This is a docs change but it is to CONTRIBUTING, not docs/src/content/docs/, so area/docs-site does not apply. The implementing PR must update CONTRIBUTING regardless of which path is chosen.

APM CEO -- Triage Arbiter

A CONTRIBUTING guide that misleads contributors is an OSS credibility issue. Path A is the right call -- modern Python projects enforce formatters in CI, and APM should too. Accept for 0.9.4. The good first issue tag is confirmed: format the codebase, add CI check, update CONTRIBUTING -- three mechanical steps with a clear definition of done.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/ci-cd", "area/testing"],
  "type": "type/refactor",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": ["good first issue"],
  "milestone": "0.9.4",
  "next_action": "Choose between Path A (format baseline + CI lint check) or Path B (remove Black/isort from CONTRIBUTING), then open a PR implementing exactly one path.",
  "comment_markdown": "Welcome, and thank you for catching this -- a CONTRIBUTING guide that generates large unexpected diffs for new contributors is a real friction point in the contributor funnel.\n\nThere are two clean paths forward:\n\n**Path A (recommended):** Format the entire codebase once (`uv run black . && uv run isort .`), commit it as a single \"apply formatter baseline\" commit, then add a `black --check` + `isort --check` step to CI. Future PRs auto-fail if they introduce drift. This is the standard approach for Python OSS projects.\n\n**Path B:** Remove the Black/isort recommendation from CONTRIBUTING.md and standardize on the existing code style without a formatter enforced in CI. Lower maintenance overhead, but the code style remains inconsistent over time.\n\nThe maintainers lean toward Path A -- it brings CONTRIBUTING, repo state, and automation into full agreement, and it's the pattern contributors expect from a modern Python project. But we want to confirm the choice before you start.\n\nIf you're happy to take this on: start with a `git config core.whitespace` check (some files may have mixed line endings on Windows) before running the formatter, and keep the formatting commit separate from any functional changes so the diff is reviewable. Happy to review!"
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.9M · ◷