Skip to content

F22.2 — One current explanation per audience

State Closed
Parent E22
Iteration Release 9
Closed Date 2026-11-17
Predecessors —

Stories: 2 Closed

Story State Depends on
S22.2.1 — Reconcile current guidance Closed (2026-11-16) —
S22.2.2 — Trim prose at the source Closed (2026-11-16) —

Give package consumers a short entry path and one maintained explanation of each contract.

Context

The root README repeats detailed package inventories in its package table and import-boundary list; the root landing page, choosing-packages guide and workspace architecture also describe package relationships. The root scaffold fixture still describes sibling requirements as git pins although E19/E21 changed them to ranges. The tooling README still recommends direct lint/import, docs and test tool invocations instead of the required task surface. Audit drift rather than treating every repeated package name as duplication.

S22.2.1 — Reconcile current guidance

State: Closed (2026-11-16)

Map current setup, package selection, boundaries, auth setup and release operations to one owning guide each. Keep concise summaries and links at entry points. Compare examples against current facades and extras.

Acceptance:

  • The root README package table is brief; package guides own API detail and workspace architecture owns graph explanation.
  • Scaffold fixture documentation describes the actual range/override behavior and uses valid package-extra examples; tooling development commands use supported task verbs.
  • A consumer can find install, minimum example, optional extras and error behavior from each package landing page.

Outcome: each topic has one owning page (setup and commands in the development guide, requiring a package in the consuming guide, the graph in workspace architecture, release steps in the release runbook), and other pages summarise and link. The root README package table is one line per package. Stale claims are fixed: no PyPI, git pins, old rn-forge-commons ranges, contract counts and extras lists. Docs use task verbs only, and every package landing page states install, a minimum example, extras and error behaviour.

S22.2.2 — Trim prose at the source

State: Closed (2026-11-16)

Audit touched public docstrings and comments against README conventions. Keep contracts and non-obvious constraints; move useful composition guidance into package guides. Eliminate stale spec/consumer history without creating duplicate reference pages.

Acceptance:

  • Docstrings changed by this epic contain contracts and generic examples; comments explain constraints rather than narrating statements.
  • Package README links remain absolute and package guide links stay within their standalone site.
  • The combined and ten standalone sites pass task docs:build.

Outcome: an audit of the public docstrings and comments E22 changed found four with rationale or narration; they now state contracts only (run_checks_sync, AppLogger.initialize, models_guard, upsert). Package README links are absolute and guide links stay within their sites.

Acceptance

  • S22.2.1: The root README package table is brief; package guides own API detail and workspace architecture owns graph explanation.
  • S22.2.2: Docstrings changed by this epic contain contracts and generic examples; comments explain constraints rather than narrating statements.