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), and the front page's scope: what is in, what is out, and which neighbour holds what is out.
  2. The first job is the review on the front page, in its five steps. A first pass is in evidence/ and names its baseline. The name stays (decision 0002).
  3. The card is standard.md: read the standard first, then the topic, then the card. Its table is generated: after changing a principle, run python3 checks/out/standard/checks/program/standard_card.py . --write.
  4. A fact that belongs to a neighbour is linked, never copied. A choice that shapes the repository gets a record in decisions/.
  5. 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, 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
  • Run the tests of the local checks (CI runs them too): python3 -m unittest discover -s checks.
  • 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 llms.txt, README.md and README.fr.md in step.
  • 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.