Contributing to this repository

For anyone changing this repository, person or language model. To apply the reader-ergonomics standard elsewhere, read its standard.md; this file is about this repository only.

Before writing

  1. Read the standard at the release this repository checks against (v1.21.0), then this repository's card, standard.md: six principles, three about counting and three about reporting, each with its grade and its check. Then the front page's scope: what is in, what is out, and which neighbour holds what is out.

  2. The first review is in evidence/case-reports, in its five steps, and names the baseline. A case follows shapes/case.md, is held to that baseline, and comes with a program that takes its counts, a test and the results of its day; case-counts, case-distinct, case-hand-counts, case-genre and case-analysis in checks/local/ check them. A count by hand is marked as such. The repository keeps its name; the frame says how the field's differs.

  3. A fact that belongs to a neighbour is linked, never copied. A choice that shapes the repository gets a record in decisions/.

  4. The briefs and start files written here are read by an agent: write them to its reader style.

Rules for claims

  • Every claim carries a grade: measured, supported with caveat, convention or not supported. A grade moves only with a cited source.
  • Cite as Author Year; the entry goes once into evidence/bibliography.md when the review starts, with a DOI, an arXiv id or a stable URL. A key names one work across the family (reader-ergonomics decision 0003): the family is listed under [bibliography_keys] in checks/config.toml.
  • Evidence against a rule goes into the review's against.md, never deleted to make a rule look stronger.
  • A number read in a summary rather than in the source is marked "(secondary)".

The model's place

  • A model explains, proposes, translates and drafts; it decides nothing. Its output is checked by a program or read by the maintainer.

Before handing back

Run the checks against the release CI uses, extracted inside this repository, in checks/out/standard, which git and the checks both skip:

rm -rf checks/out/standard && mkdir -p checks/out/standard
git -C ../reader-ergonomics archive 2e5b6f0 | tar -x -C checks/out/standard   # the commit checks.yml pins
python3 checks/out/standard/checks/run.py . --tiers program,meaning --judge flag   # the repository, as CI runs it
READER_ERGONOMICS_CHECKS=checks/out/standard/checks python3 -m unittest discover -s checks   # the tests of checks/local/
python3 checks/out/standard/checks/program/standard_card.py . --write   # rebuild the card's table and llms.txt after a principle changes
  • Fix every error. Read every warning.
  • Answer the questions in checks/out/needs-judgment.md in checks/judgments.toml, each answer quoting in backticks a word or heading of its own file.
  • Keep README.md and README.fr.md in step. llms.txt and the table of the card are generated from the principle files by the command above.
  • A pin raise goes in CHANGELOG.md, not in decisions/.

House conventions

  • No em dash or en dash in prose; use a comma, a colon, parentheses, or a hyphen for ranges.
  • Commit messages follow the standard's commit shape: a subject of at most 72 characters, then why.
  • The maintainer decides every push.