diff --git a/docs/dev/contributing.md b/docs/dev/contributing.md index 7627db2..16d68d0 100644 --- a/docs/dev/contributing.md +++ b/docs/dev/contributing.md @@ -25,13 +25,15 @@ just test # pytest with coverage - `ruff format` enforces formatting; do not hand-format. - Type-check with `ty` (Astral). Use `# ty: ignore[]` for suppressions, not `# type: ignore`. - Do NOT use `from __future__ import annotations`. Python 3.11+ is the floor. -- Module docstrings are required; per-method docstrings only when types alone are insufficient. +- Module, class, and public-method docstrings are required (PEP 257); see + [`architecture/conventions.md`](https://github.com/modern-python/httpware/blob/main/architecture/conventions.md). ## Architecture invariants -These are project invariants. The CI lint pass (`just lint-ci` — `ruff` + `ty`) -catches what the linters can see (e.g. `print()` via ruff `T201`); the rest are -enforced in code review. Do not break them in pull requests: +These are project invariants — see +[`architecture/overview.md`](https://github.com/modern-python/httpware/blob/main/architecture/overview.md) for exactly which +ones CI machine-checks, partially checks, or leaves to review. Do not break +them in pull requests: - No `httpx2._*` (private API) usage anywhere in the library. - No `from __future__ import annotations`. diff --git a/planning/audits/2026-07-13-docs-comments-audit.md b/planning/audits/2026-07-13-docs-comments-audit.md index cf53f0e..0760510 100644 --- a/planning/audits/2026-07-13-docs-comments-audit.md +++ b/planning/audits/2026-07-13-docs-comments-audit.md @@ -63,12 +63,14 @@ Verified against source: the `try/except Exception: raise DecodeError(...)` live `contributing.md`: `"Module docstrings are required; per-method docstrings only when types alone are insufficient."` (conditional) `conventions.md`: `"Module / class / public-method docstrings are required ..."` (unconditional) *Fix:* pick one policy and make both files say it — recommend keeping `conventions.md`'s unconditional wording since it's the capability truth home, and updating `contributing.md` to match. +**Resolved** (`2026-07-13.08`) — maintainer ruled unconditional; `contributing.md` now links to `conventions.md` instead of restating. **I3 — `docs/dev/contributing.md:32-34` understates what CI machine-checks, vs `architecture/overview.md:9`.** `contributing.md`: `"The CI lint pass (...) catches what the linters can see (e.g. print() via ruff T201); the rest are enforced in code review."` — reads as "only `print()` is machine-checked." `overview.md`: documents two more checks contributing.md omits — `PGH003` (blanket `# type: ignore`) is machine-checked, and `SLF001` partially checks the `httpx2._` ban (attribute access, not import). This is a fresh drift, not a re-flag of the 2026-06-13 audit's I1 (that finding was about a since-removed "CI grep gates" phrase, already fixed) — `overview.md`'s finer breakdown was apparently added after `contributing.md`'s wording was last touched. *Fix:* replace `contributing.md`'s "the rest are enforced in code review" with the same three-tier breakdown `overview.md` uses (machine-checked / partially-checked / review-only), or have it link to `overview.md` instead of restating. +**Resolved** (`2026-07-13.08`) — maintainer ruled link-instead-of-restate, per the repo's truth-home principle. **I4 — `docs/testing.md:110` says `httpx` where it means `httpx2`.** `"MockTransport is the public test seam in httpx — supported by the maintainers, stable across versions ... respx patches private internals and has historically broken across httpx major versions."` @@ -98,14 +100,12 @@ Same argument, ~3 near-identical sentences in each. Bundle this cleanup with the - **`2026-07-13.07-docs-comments-audit-fixes`** (lightweight) — fixes C1, C2, I1, I4. Verified against source; `just lint-ci`, `mkdocs build --strict`, and `just test` (780 passed, 100% coverage) all clean. +- **`2026-07-13.08-contributing-docstring-ci-wording`** (lightweight) — fixes + I2, I3 per maintainer ruling (unconditional docstrings; link instead of + restate). Verified: `mkdocs build --strict`, `just lint-ci` clean. ## Deferred / next steps -- **Needs your call:** I3's fix direction (restate the three-tier breakdown in - `contributing.md`, or replace it with a link to `overview.md`) and I2's - policy choice (unconditional vs conditional method-docstring requirement) — - both are wording contradictions where either side could be "the fix," - not a clear code-vs-doc mismatch. Not yet scheduled. - **Compaction:** D1 (`ResponseTooLargeError` triplication) and D2 (bundled with I4's `httpx`/`httpx2` fix — the "why not respx" duplication itself wasn't touched by `2026-07-13.07`, only the terminology slip within it) are diff --git a/planning/changes/2026-07-13.08-contributing-docstring-ci-wording.md b/planning/changes/2026-07-13.08-contributing-docstring-ci-wording.md new file mode 100644 index 0000000..9d2e1f0 --- /dev/null +++ b/planning/changes/2026-07-13.08-contributing-docstring-ci-wording.md @@ -0,0 +1,41 @@ +--- +summary: Fixed 2 verified wording contradictions from the docs-and-comments audit — contributing.md's docstring requirement now matches conventions.md (unconditional), and its CI-enforcement claim links to overview.md instead of restating a stale subset. +--- + +# Change: Resolve contributing.md wording contradictions (I2, I3) + +**Lane:** lightweight — 1 file, docs-only, no code, no public-API change. + +Spec: [`planning/audits/2026-07-13-docs-comments-audit.md`](../../audits/2026-07-13-docs-comments-audit.md) +(findings I2, I3). Both were policy-wording calls, not code-vs-doc mismatches, +resolved by the maintainer: + +- **I2** — `contributing.md` said per-method docstrings are required "only + when types alone are insufficient"; `conventions.md` says public-method + docstrings are unconditionally required. Maintainer ruling: unconditional + wins — `conventions.md` is the capability truth home. +- **I3** — `contributing.md` implied only `print()` is CI-machine-checked; + `overview.md` documents a finer 3-tier breakdown (machine-checked / + partially-checked / review-only). Maintainer ruling: link instead of + restate, per the repo's own truth-home principle (the same one D1/D2 in the + audit flagged when violated the other way). + +## Approach + +`docs/dev/contributing.md`'s "Code style" and "Architecture invariants" +sections now point at `architecture/conventions.md` and +`architecture/overview.md` respectively instead of carrying their own +(drifted) copies of the same facts. + +## Files + +- `docs/dev/contributing.md` — I2 docstring-requirement line now unconditional + + links to `conventions.md`; I3 CI-enforcement paragraph now links to + `overview.md` instead of restating a stale subset. + +## Verification + +- [x] `mkdocs build --strict` succeeds (relative links resolve). +- [x] `just lint-ci` — clean. +- [x] Final read-through — no residual "only when types alone are + insufficient" / "the rest are enforced in code review" wording remains.