From 9724d2dd21e7bbc199accb712b7c94e6b9736d72 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 14 Jun 2026 11:41:11 +0300 Subject: [PATCH 1/2] chore(planning): archive shipped docs-ux-restructure bundle Shipped via #60; promote 2026-06-14.01 out of active/ (status: shipped, pr: 60). Index Active is now empty. Co-Authored-By: Claude Opus 4.8 (1M context) --- planning/README.md | 3 ++- .../2026-06-14.01-docs-ux-restructure/design.md | 6 +++--- .../2026-06-14.01-docs-ux-restructure/plan.md | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) rename planning/changes/{active => archive}/2026-06-14.01-docs-ux-restructure/design.md (96%) rename planning/changes/{active => archive}/2026-06-14.01-docs-ux-restructure/plan.md (99%) diff --git a/planning/README.md b/planning/README.md index 12b33f1..e964e94 100644 --- a/planning/README.md +++ b/planning/README.md @@ -70,10 +70,11 @@ carry **no** frontmatter — living prose, dated by git. ### Active -- **[docs-ux-restructure](changes/active/2026-06-14.01-docs-ux-restructure/design.md)** (draft, 2026-06-14) — Thin README front-door + canonical `docs/index.md`, why-httpware hook (G1), runnable first example (G4), nav nits, base-client scrub. G2 dropped, G6 deferred. +_None._ ### Archived (shipped) +- **[docs-ux-restructure](changes/archive/2026-06-14.01-docs-ux-restructure/design.md)** (#60, 2026-06-14) — Thin README front-door + canonical `docs/index.md` (G3), why-httpware hook (G1), runnable jsonplaceholder example (G4), nav reorder + architecture links, base-client scrub. G2 dropped; G6 (decoder guide) still open. - **[docs-audit-followups](changes/archive/2026-06-13.05-docs-audit-followups/change.md)** (#58, 2026-06-13) — Second docs-audit batch: corrected the overstated invariant-enforcement claims in `CLAUDE.md` + `architecture/overview.md` (only `print()`/blanket-`type: ignore` are machine-checked), readability findings R1–R3, and documented the public `STATUS_TO_EXCEPTION` (G5). - **[docs-accuracy-fixes](changes/archive/2026-06-13.04-docs-accuracy-fixes/change.md)** (f203821, 2026-06-13) — Fixed 5 verified factual errors from the [docs audit](audits/2026-06-13-docs-audit.md): RetryBudget formula, modern-di 2.x recipe, contributing-doc CI/grep claim, `just lint` comment, middleware stable-contracts list (+ AsyncTimeout non-finite wording). - **[portable-planning-convention](changes/archive/2026-06-13.03-portable-planning-convention/design.md)** (#55, 2026-06-13) — Adopt the portable two-axis convention: per-capability `architecture/` truth files + `changes/` bundles, full history backfill, byte-identical Conventions. diff --git a/planning/changes/active/2026-06-14.01-docs-ux-restructure/design.md b/planning/changes/archive/2026-06-14.01-docs-ux-restructure/design.md similarity index 96% rename from planning/changes/active/2026-06-14.01-docs-ux-restructure/design.md rename to planning/changes/archive/2026-06-14.01-docs-ux-restructure/design.md index 353d7ea..ab42d58 100644 --- a/planning/changes/active/2026-06-14.01-docs-ux-restructure/design.md +++ b/planning/changes/archive/2026-06-14.01-docs-ux-restructure/design.md @@ -1,11 +1,11 @@ --- -status: draft +status: shipped date: 2026-06-14 slug: docs-ux-restructure supersedes: null superseded_by: null -pr: null -outcome: null +pr: 60 +outcome: Shipped via #60 (squash 480cea8) — thin README front-door + canonical docs/index.md (G3), why-httpware hook (G1), runnable jsonplaceholder example (G4), nav reorder + architecture links, base-client scrub. G2 dropped; G6 (decoder guide) still open. --- # Design: Docs-UX restructure — thin README, canonical site, runnable first example diff --git a/planning/changes/active/2026-06-14.01-docs-ux-restructure/plan.md b/planning/changes/archive/2026-06-14.01-docs-ux-restructure/plan.md similarity index 99% rename from planning/changes/active/2026-06-14.01-docs-ux-restructure/plan.md rename to planning/changes/archive/2026-06-14.01-docs-ux-restructure/plan.md index d890006..992b02b 100644 --- a/planning/changes/active/2026-06-14.01-docs-ux-restructure/plan.md +++ b/planning/changes/archive/2026-06-14.01-docs-ux-restructure/plan.md @@ -1,9 +1,9 @@ --- -status: draft +status: shipped date: 2026-06-14 slug: docs-ux-restructure spec: docs-ux-restructure -pr: null +pr: 60 --- # docs-ux-restructure — implementation plan From 1a84d2a11f7c90a4a558485cab2d5c7a446f5873 Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sun, 14 Jun 2026 11:44:36 +0300 Subject: [PATCH 2/2] docs(planning): defer the custom-ResponseDecoder guide (G6) Park audit finding G6 in deferred.md (Documentation) as demand-gated, and note the resolution in the audit report. Closes out the docs-audit register. Co-Authored-By: Claude Opus 4.8 (1M context) --- planning/audits/2026-06-13-docs-audit.md | 3 ++- planning/deferred.md | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/planning/audits/2026-06-13-docs-audit.md b/planning/audits/2026-06-13-docs-audit.md index 5d07246..2cb0537 100644 --- a/planning/audits/2026-06-13-docs-audit.md +++ b/planning/audits/2026-06-13-docs-audit.md @@ -158,7 +158,8 @@ follow them. No orphan pages and no broken nav targets — the nav is otherwise all five bare `architecture/*.md` references converted to absolute GitHub links. Only **G6** (custom-`ResponseDecoder` guide; no API reference per maintainer) -remains open after `2026-06-14.01`. +remains open after `2026-06-14.01` — now parked in the long-tail register, +[`deferred.md`](../deferred.md) (Documentation), demand-gated. ### Verified correct (negative results) diff --git a/planning/deferred.md b/planning/deferred.md index a54caad..54e09b1 100644 --- a/planning/deferred.md +++ b/planning/deferred.md @@ -33,3 +33,7 @@ As of 0.7.0, all planned epics (3, 4, 5, 6) are closed — see the [change Index Three separable additions, rough priority: **(a) rate-over-window trip mode** (the core ask; additive opt-in), **(b) manual control + read-only `state`** (independent; both libraries have it, httpware parked it as YAGNI), **(c) slow-call-rate dimension** (don't — covered by `AsyncTimeout`). **Concurrency note:** the window recorder (ring buffer for count-based; time-bucketed counters for time-based) is more state than v1's single counter, but recording an outcome stays a synchronous mutation, so the async lock-free atomicity invariant and the sync `threading.Lock` both still hold. Time-based eviction must read `_now()` inside the same synchronous critical section. + +### Documentation + +- **Custom-`ResponseDecoder` guide** (audit finding G6, [2026-06-13 docs audit](audits/2026-06-13-docs-audit.md)) — the decoder seam (Seam B) is a documented extension point, but unlike middleware it has no "write your own" guide. A short page would show the `can_decode(model: type) -> bool` / `decode(content: bytes, model: type[T]) -> T` protocol, how `decoders=[...]` ordering resolves a model, and a worked third-party-adapter example. Decided alongside the `2026-06-14.01` docs-UX restructure: **defer the guide, and ship no auto API reference / mkdocstrings** (prose carries the signatures). Demand-gated. Revisit trigger: someone asks how to write a custom decoder, a third-party decoder adapter ships, or the `decoders/` protocol surface changes. (`docs/`, `src/httpware/decoders/`)