Repository navigation
Adds why the family shares one type registry - #45
Merged
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 newExplanationgroup ingroups_for_extras, anddocs/explanationis inpackage.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.mdexcludes 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 againstStatifierDatamodel.Types.satisfies/3, the nominal rule and the host relation against theStatifierDatamodel.Typesmoduledoc, and the optional dependency between the two editors against theirmix.exsfiles.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.enabled: true: status ok, no finding.