Contributing to this repository

For anyone changing this repository, person or language model. To apply the standard somewhere else, read standard.md instead; this file is about this repository only. To extend it to one genre in a repository of its own, read extending.md, and change nothing it lists as the interface without raising the major version.

Before writing

  1. Read standard.md. This repository is its own first example, so it obeys every principle it states.
  2. Pick the shape of what you write from shapes/, and the reader style if the reader is known (reader-styles/).

Rules for claims

  • Every principle carries a grade: measured, supported with caveat, convention or not supported. A grade moves only with a cited source. A claim whose clauses rest on evidence of different strength grades each clause (decision 0006).
  • Cite in the text as Author Year. The full entry goes once into evidence/bibliography.md, with a DOI, an arXiv id or a stable URL. A key names one work, here and in every extension (decision 0003); an organisation's second work of a year may take a title word instead of a letter, Microsoft 2026 icons (decision 0004).
  • Evidence against a principle goes into the topic's against.md, never deleted to make a principle look stronger.
  • A number read in a summary rather than in the paper is marked "(secondary)".
  • A limit or caveat added to a principle carries its own grade and its kind of source (study, thesis, standard, company page, opinion), and the change obeys the principle it changes. Practice shows what is done; an outcome it reports is its owner's claim.

Before handing back

python3 -m unittest discover -s checks     # the checks' own oracle
python3 checks/run.py .                    # the repository against the standard
python3 checks/run.py . --online --only references   # resolve every reference (network)
  • Fix every error. Read every warning.
  • Answer the questions in checks/out/needs-judgment.md, and keep each answer in checks/judgments.toml, quoting what in the file the reason rests on. A model does not review its own text in place of the checks.
  • The paid judgment backend stays off ([judgment.api] enabled = false) unless the maintainer turns it on.

Generated files

python3 checks/program/standard_card.py . --write rebuilds llms.txt, the principle table and the counts. In llms.txt, a line that is exactly <!-- hand --> starts the part kept by hand: that line and everything after it survive a rebuild, so a proof page, a design document or an experiments folder stays listed. Put the links to such pages below it, never above.

House conventions (this repository, not the standard)

  • English throughout; the two READMEs are kept in English and French, in step.
  • No em dash or en dash in prose; use a comma, a colon, parentheses, or a hyphen for ranges.
  • A new folder gets a README.md and a one-line index.qmd that includes it (copy any existing index.qmd), because the site generator skips files named README.
  • Commit messages follow shapes/commit.md.
  • A release adds its entry at the top of CHANGELOG.md, and sets version and date-released in CITATION.cff to match, before it is tagged (release-version checks the two agree).

The site

quarto render builds _site/ locally. A push to master publishes it through .github/workflows/pages.yml.