Upgrade guide covers every release up to the current one #707

Parent

#698

What to build

The upgrade guide stops at 0.15 while the package is at 0.25.0, and one recipe subclasses ferro.Ferro, which does not exist. Each release from 0.16 to the current one gets a section listing what an upgrade asks of the user (from CHANGELOG.md and the release PRs), and every before/after recipe uses real classes, shows both declaration styles, and runs. The implicit-routing removal is attributed to the release CHANGELOG.md records (0.14).

Pages: howto/upgrade-guide.md

Acceptance criteria

• Every fact on the page matches the code at the time of the PR; each High finding in the audit rows below is fixed, and each Medium/Low finding is fixed or answered in the PR body with the reason it was left.
• Each page is one kind (tutorial, how-to, reference or explanation) and opens with one sentence saying what it covers, then an example on the first screen (writing-for-humans rules 1–2).
• Each page uses one running example, declared once near the top and reused; each section shows only what changed (rule 3).
• Every code block has a lead-in sentence ending in a colon and a result sentence after it, and shows its result: printed output, or the asserted value inside the embedded snippet range (rules 7–8). Snippet end: markers sit below the assert or print that holds the result.
• Every copyable block either shows the async with engines.session(): wrapper or sits under a sentence that says it runs inside one and links to Connections › Sessions; the page's first block shows the wrapper.
• Every inline Python block that does real work runs under the harness ({test=run prelude=<name>}) or moves into an example script; a block left compile-only says why in its fence marker.
• Every lambda passed to a query method names its parameter after the model in lowercase singular (AGENTS.md I-8); python -m tests._docs_checks reports no violation for the owned files.
• Every error check in an owned example fails when the expected error is not raised (try/except/else: raise AssertionError, or the harness helper).
• Field-declaring examples show both declaration styles as tabs, each backed by a runnable script (AGENTS.md I-7), and the twins use the one Annotated idiom recorded in the docs conventions.
• Headings are short sentence-case noun phrases naming the feature (rule 5); how-to titles name the goal (rule 24); no minimising words (rule 17); admonitions follow rule 20.
• No ADR numbers, issue numbers, codenames, dated or release-bound notes, or contributor-only references in page text; version markers are self-contained blocks at the end of a section.
• Reference material that has a home in Reference is linked, not repeated; each topic ends with a pointer to its reference entry (rule 4).
• Every version from 0.16.0 to the version in pyproject.toml has a section, or a one-line note that it needs no action.

Files owned

• Create: docs/examples/upgrade_*.py (one pair per recipe that declares fields)
• Modify: docs/pages/howto/upgrade-guide.md

Interfaces

• Consumes: I-8, I-14, docs conventions (AGENTS.md ticket (AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703))
• Consumes: {test=run prelude=<name>}, tests._docs_checks (harness ticket (Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704))
• Produces: nothing other tickets rely on

Test scenarios

• Happy path: the strict site build succeeds and every snippet range on the owned pages renders without leading indentation.
• Happy path: every owned example script runs to completion under tests/test_docs_examples.py, and every inline block marked {test=run ...} runs.
• Error path: deleting the raise an owned example's error check expects makes that example's test fail.
• Edge case: python -m tests._docs_checks over the owned files exits 0; renaming one lambda parameter to t makes it exit 1 naming the file and line.

Verify

uv run --no-sync zensical build --clean --strict
uv run --no-sync pytest tests/test_docs_examples.py -q --no-cov -p no:cacheprovider -n 8
uv run --no-sync python -m tests._docs_checks docs/pages/howto/upgrade-guide.md

Blocked by

• Docs site config: Zensical features, Markdown extensions, API reference options and a strict build #701, AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703, Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704

Audit findings