Skip to content

Adds why the family shares one type registry - #45

Merged
johnnyt merged 1 commit into
mainfrom
sd-tuz-why-the-family-shares-one
Oct 5, 2026
Merged

johnnyt merged 1 commit into
mainfrom
sd-tuz-why-the-family-shares-one

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 5, 2026

Copy link
Copy Markdown
Member

Adds an explanation page, "Why the family shares one type registry", and links it from the README's Understand list.

What changes

  • docs/explanation/why-one-type-registry.md (new): why the block editor and the expression editor read the datamodel document through one package, why that package depends on nothing else in the family, why it returns facts rather than verdicts, the alternatives weighed (the reader kept in the block editor's package with a plain map handed across, a reader per tool, a second artifact for the types, a separate registry for what a screen's text reads), and what the arrangement costs (slower to change, nominal record identity, a closed type set). Examples are set in the library loan. The page has no numbered steps and no instructions.
  • mix.exs: the page is an extra in a new Explanation group in groups_for_extras, and docs/explanation is in package.files, because the README links the page by a relative path.
  • README.md: one line under Understand. No README text is replaced: the "Why this package" section is the README's own short why, and the page goes further than it rather than taking its place.

No file under lib/ changes. No changelog fragment: changelog.d/README.md excludes documentation.

Source

The docs audit for this repository names no section whose next action is this page, so it is written from the package moduledoc (StatifierDatamodel), the README, and the Context, Consequences and Alternatives sections of the decision records. Each claim about the code was checked on main: the read check's answers against StatifierDatamodel.Types.satisfies/3, the nominal rule and the host relation against the StatifierDatamodel.Types moduledoc, and the optional dependency between the two editors against their mix.exs files.

Checks

  • mix quality: green (format, compile, doc links, dependencies, docs, credo, 137 of 137 tests at 99.1% coverage, dialyzer).
  • mix docs --warnings-as-errors: no warnings; the page renders in the sidebar under Explanation, and its module references resolve to the module pages.
  • Doc links stage run by hand with enabled: true: status ok, no finding.
  • README lint against the docs manifest: every part present, no finding.

An explanation page under docs/explanation: why the block editor and
the expression editor read the datamodel document through one package
that depends on neither, why it returns facts rather than verdicts,
the alternatives weighed, and what the arrangement costs. Examples
are set in the library loan.

The page is an extra in a new Explanation group and ships in the
package files, since the README's Understand list links it by a
relative path.

Refs: sd-tuz
@johnnyt
johnnyt merged commit ebbf82e into main Oct 5, 2026
1 check passed
@johnnyt
johnnyt deleted the sd-tuz-why-the-family-shares-one branch October 5, 2026 11:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant