docs: correct invariant-enforcement claims + readability follow-ups#58
Merged
Conversation
Second batch of docs-audit follow-ups (audit: planning/audits/2026-06-13-docs-audit.md).
Invariant enforcement (triage item, option 2 — fix the claim):
Empirically confirmed against ruff --select ALL that the "(CI-enforced) / CI
rejects PRs" heading was overstated. Only print() (T201) and a blanket
# type: ignore (PGH003) are machine-checked; httpx2._ is partial (SLF001 catches
attribute access, not a used private import); the future-import, global-logging,
and # ty:-vs-# type: rules are review-only. Rewrote the heading + intro in
CLAUDE.md and architecture/overview.md to the real split and reframed the
httpx2._ grep as a review check, not a CI gate.
Readability + small-gap findings:
- R3 errors.md: examples used _LOGGER undefined; added import logging +
_LOGGER = logging.getLogger("myapp") and a note.
- G5 errors.md: documented the public STATUS_TO_EXCEPTION mapping (lone
undocumented __all__ export).
- R2 README: glossed Finagle-style RetryBudget (token bucket capping global
retry rate) and PEP 678 note.
- R1 README + resilience.md: de-densified the decoder-resolution sentence and
the respect_retry_after table cell.
Change bundle: planning/changes/active/2026-06-13.05-docs-audit-followups/
mkdocs build --strict and just lint both clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lesnik512
added a commit
that referenced
this pull request
Jun 14, 2026
Both docs-audit fix bundles have shipped, so promote them out of active/ per the planning convention: - 2026-06-13.04-docs-accuracy-fixes -> archive/ (status: shipped; pushed to main as f203821) - 2026-06-13.05-docs-audit-followups -> archive/ (status: shipped; #58) Index "Active" is now empty; both lines moved to "Archived (shipped)". Docs-only/bookkeeping; no code or capability change. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second batch of follow-ups from the docs audit. The first batch (verified bugs B1/B2/I1/I2/I3) already landed on
main; this PR covers the invariant-enforcement claim fix plus the readability/small-gap findings.Invariant enforcement — fix the overstated claim
The "(CI-enforced) / CI rejects PRs that violate them" heading was wrong. Verified empirically against the real
ruff --select ALLruleset:print()T201# type: ignorePGH003httpx2._private APISLF001catches attribute access, not a used private import (from httpx2._x import …)from __future__ import annotationslogging.basicConfig()/ baregetLogger()Rewrote the heading + intro in
CLAUDE.mdandarchitecture/overview.mdto state the actual split, and reframed thehttpx2._grep as a review check (it is not wired into CI).Readability + small-gap findings
docs/errors.md— examples used_LOGGERundefined (copy-pasteNameError); addedimport logging+_LOGGER = logging.getLogger("myapp")and a note.docs/errors.md— documented the publicSTATUS_TO_EXCEPTIONmapping (the lone undocumented__all__export).README.md— glossed "Finagle-styleRetryBudget" (token bucket capping the global retry rate) and "PEP 678 note".README.md+docs/resilience.md— de-densified the decoder-resolution sentence and the run-onrespect_retry_aftertable cell.Verification
mkdocs build --strict— clean (no broken refs)just lint— clean (no source touched)Still open (separate, design-led work)
The structural docs-UX gaps need a
design.md, not mechanical edits: G1 why-httpware, G2 base-client migration guide, G3 de-dup README ↔ index.md, G4 runnable quickstart, G6 custom-decoder guide + mkdocstrings API reference, plus nav-ordering nits.🤖 Generated with Claude Code