[TASK] Clarify `black` formatting guidance in CONTRIBUTING.md

[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.

[github-actions]

Triage decision

accept

Proposed labels

area/docs-site
area/ci-cd
type/docs
status/accepted
priority/low

Milestone

0.9.4

Suggested next action

Update CONTRIBUTING.md to remove the black formatter reference and document what APM actually enforces in CI (or state that no specific formatter is required).

Suggested issue comment

Thanks for filing this, and thanks to `@jacobokeeffe-ow` for surfacing it in #688. The `black` reference in CONTRIBUTING.md causes genuine contributor friction: running `uv run black .` reformats 308 files and leaves contributors choosing between noisy PRs or ignoring the guide.

The fix is to align CONTRIBUTING.md with what APM actually enforces in CI. Since `black` is not wired into any CI gate, the simplest path is to remove the reference (or add a note that no auto-formatter is required and contributors should not include reformatting commits in their PRs). A second option is to add `ruff format` to CI -- but that is a larger scope change.

If you want to take this as a docs PR, the scope is a targeted edit to CONTRIBUTING.md (and a quick grep to catch any other references to `black` as a required step).

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is "contribute code without introducing noise." CONTRIBUTING.md references black as a formatter, but running it reformats 308 files that CI does not enforce. This is a classic guide-vs-gate mismatch. The npm/pip/cargo mental model is that contribution guides describe exactly what the CI gate requires. Fixing the guide resolves the mismatch directly and unblocks contributors who followed the guide in good faith.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. This is a pure contributor-guide documentation fix; no packaging, lockfile, marketplace, MCP config, or auth surface is touched.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- sergio-sisternes-epam is an established collaborator with extensive prior interactions on microsoft/apm; warmth tuning for a new contributor is not needed.

Python Architect -- Architecture Reviewer

Not activated -- this is a documentation fix; no cross-cutting design decision, interface change, data model, or migration boundary is involved.

Doc Writer -- Documentation Reviewer

The fix targets CONTRIBUTING.md, a contributor-facing guide. area/docs-site is the closest taxonomy fit for documentation work; no new page in docs/src/content/docs/ is required. The proposed wording is clear and grounded in the contributor vocabulary already used in the guide.

APM CEO -- Triage Arbiter

Clear, self-contained docs fix. The guide should describe exactly what CI enforces -- no more, no less. Accept at priority/low for 0.9.4: low risk, unblocks any contributor who followed the guide literally. No theme label needed; this is pure infra (area/docs-site + area/ci-cd) with no product surface implication.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/docs-site", "area/ci-cd"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Update CONTRIBUTING.md to remove the `black` formatter reference and document what APM actually enforces in CI.",
  "comment_markdown": "Thanks for filing this, and thanks to `@jacobokeeffe-ow` for surfacing it in #688. The `black` reference in CONTRIBUTING.md causes genuine contributor friction: running `uv run black .` reformats 308 files and leaves contributors choosing between noisy PRs or ignoring the guide.\n\nThe fix is to align CONTRIBUTING.md with what APM actually enforces in CI. Since `black` is not wired into any CI gate, the simplest path is to remove the reference (or add a note that no auto-formatter is required and contributors should not include reformatting commits in their PRs). A second option is to add `ruff format` to CI -- but that is a larger scope change.\n\nIf you want to take this as a docs PR, the scope is a targeted edit to CONTRIBUTING.md (and a quick grep to catch any other references to `black` as a required step)."
}

---

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 · ● 2.3M · ◷