Skip to content

Docs follow-ups from the #777 panel: run the Postgres-only blocks (F25), issue numbers in error messages, refused models stay registered #781

Open

Description

@0x054

Problem

Three things surfaced while fixing the review panel's findings on the docs-rewrite PR (#777) that are outside that fix round's scope.

Items

  1. Postgres-only blocks still compile-only (panel F25). About a dozen page blocks (concepts/backends.md, guide/connections.md, guide/raw-sql.md, guide/row-level-security.md, guide/schema/auto-migrate.md, and Session.set_config's docstring) are marked {test=compile reason="needs a PostgreSQL server"} although the suite has a live Postgres under the postgres_only marker. Running them needs a fence setting such as {test=run prelude=<name> backend=postgres}, a Postgres twin of the preludes that connect (a patched connect() URL), the fence tests split so the Postgres half runs in the backend-matrix job, and Litestar/FastAPI installed for the two framework blocks. Story 4 of Docs rewrite: every snippet runs, every fact matches the code, and the API reference renders cleanly #698 asks that every copyable block be executed.
  2. Error messages carry issue numbers into the docs. The printed-output gate (docs: panel round 1 on #777 (harness and pages) — output blocks regenerated, one fence reader and runner, twin equivalence, CLI reference complete #780) regenerates error blocks from Ferro's real messages, and several contain references such as (#291). The pages rule (and I-14 for docstrings) keeps issue numbers out of reader-facing text, but these come from src/. Decide whether exception texts should name issues at all; if not, remove them from the messages (the regenerated blocks then update themselves).
  3. A model Ferro refuses at class definition stays in the registry. Found while regenerating the aggregation error blocks: when the metaclass raises for a bad declaration, the partially built class remains registered, so a later create_tables() or lookup can meet it. Looks like a src/ferro/registry.py / metaclass bug; a refused class should leave no trace.

Related

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-triageNeeds evaluation by a maintainer

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions