How to contribute

This book is the group’s shared workspace, not a finished text. Notes, readings, corrections, and disagreements are all welcome. Everything below is also in CONTRIBUTING.md at the repository root, which is what GitHub shows when you open a pull request.

What must never be published here

The repository is public. Before committing anything, check that it contains none of the following.

  • Journal PDFs or article full texts. This book distributes links and bibliographic metadata only. Publishers’ terms are not waived by course use. Put reading copies in private/pdfs/, which is ignored by git.
  • Unpublished data or results, yours or a collaborator’s, including figures from work in review.
  • Anything a collaborator, student, or reviewer has not agreed to make public. The case exercises ask people to describe how their own projects really went, which is exactly the material that should stay in the private group notes.
  • Anything from private/. That directory holds the parallel analysis and is excluded by .gitignore; tools/validate.py fails if the ignore rule is missing or if private material is registered as a chapter. Do not defeat either guard.

If you are unsure, ask before committing rather than after. A commit that reaches the public history is not fully undone by a later deletion.

Status labels

Every page carries one of three labels under its title, and the front page keeps the table of where things stand.

  • Drafted proposed by the convenor or the assistant; not yet discussed by the group
  • Discussed taken up in a meeting; the notes say what was said
  • Adopted a group decision

Flip a label by editing the line under the title and the row in the front-page table, in the same pull request as the meeting note. The public pages are bullet-level on purpose; the full text and analysis behind them live in the private repository under text/.

Adding a meeting note

Open meeting notes, find your meeting, and add a signed, dated entry. The “Edit this page” link in the right-hand margin opens the file on GitHub and turns your edit into a pull request without a local clone.

Do not edit someone else’s entry. If you disagree, add your own beneath it and say so. The record is more useful for keeping the disagreement than for resolving it.

Adding a reading

Two files are the sources of truth, and they change together:

  1. Append a BibTeX record to references.bib. Give it a key of the form author plus year, a DOI verified against Crossref, and a url that resolves.
  2. Add the matching entry to the references object in curriculum.json: author, year, title, journal, DOI, volume, issue, pages, URL, and an access note.

Then decide where it belongs. A suggestion for the group goes as a bullet in the bibliography, citing the key, with one sentence on the claim and one on the meeting it bears on. An optional extension for a meeting goes in that meeting’s optional list in curriculum.json and as a cited bullet on the session page, with a sentence or two on why it is there. In either case run tools/build_bibliography.py, which regenerates the reading lists on the bibliography page from curriculum.json; tools/validate.py fails if those lists are stale, if the BibTeX keys and the metadata disagree, or if an optional key is not cited on its session page.

Adding a prior-art entry

Prior art catalogues systems and benchmarks rather than readings, so it takes a table row rather than a bibliography entry. Include a resolvable DOI or arXiv ID and fill in the last column honestly: what the project’s numbers do not establish. An entry that overstates a limitation is as much a problem as one that omits it. Say so in the pull request if you have actually run the system.

Changing the curriculum

Session pages and curriculum.json hold the same prose; validation checks the title, reading roles/instructions, question, contrast, preparation, exercise, output, and mode links. Change both together. The pair array is ordered anchor then companion; required errata belong in corrections, background in optional. There are thirteen meetings, numbered in order, without fixed dates.

Substantive changes to what is assigned should start as an issue, and the rationale belongs in READING-AUDIT.md alongside the existing entries.

Revising a mode

  • Edit the authoritative specification in modes/; record the case and evidence motivating a change.
  • Update mode_version for a substantive revision. A drafted definition is not a record of group adoption.
  • Run tools/export_modes.py to regenerate agents/mode-instructions.json. Agents and evaluation records retain the source version and hash; do not edit the generated instructions separately.
  • New profiles need chapter registration in _quarto.yml and links from the glossary. The number of profiles is not fixed by the validator.

Checking your work before you push

python3 -m venv .venv
.venv/bin/pip install PyYAML
.venv/bin/python tools/export_modes.py
.venv/bin/python tools/build_bibliography.py
.venv/bin/python tools/validate.py
quarto render

A virtual environment rather than a plain pip install because recent macOS and Linux Pythons refuse to install into the system interpreter. .venv/ is gitignored.

validate.py checks chapter existence, local links, citation keys, the schedule, the agreement between references.bib and curriculum.json, and that the generated reading lists in bibliography.qmd are current, then runs a Pandoc citation pass that fails on any warning. The same checks run on every pull request.

If you changed a reference or added a prior-art entry, also run .venv/bin/python tools/check_links.py. It verifies every DOI against Crossref and fetches every other URL. A handful of publisher sites answer automated requests with 403; the script reports those separately and does not treat them as failures.

Style

Match the surrounding pages. The book states what a source does and does not establish, labels reconstruction as inference, and avoids treating a first-person account, a philosophical argument, and a controlled study as interchangeable evidence. Keep claims proportionate to what was actually shown, and prefer “no precedent located within this search” to “never done before”.