# Contributing

## One fix, one test

Every change to a rule comes with the vector or fixture that shows it.
Change the oracle in `tools/oracle/` and the chapter together, run `python3 tools/build.py` to regenerate the vectors and fixtures, and commit the regenerated files with the change.
`python3 tools/check.py` must pass.

A fixture that breaks something belongs in `fixtures/invalid/`, with the rule it breaks in `expect.json`, built by `tools/build.py` like the others.
Rule IDs are stable: a rule's meaning never changes, and a retired ID is never reused.

## Versions

A change that makes a valid file invalid, or changes any computed value, is breaking: it needs a new major version of the format and a migration in `scienting-core`.
Adding an optional property, a kind or an enumeration value is a minor change.
Record each change in [CHANGELOG.md](CHANGELOG.md), and each departure from the design in [DECISIONS.md](DECISIONS.md).

## Prose

US English, one sentence per line, so a change to a sentence is a one-line diff.
Prefer plain words to abbreviations; write "for example", not "e.g.".
`tools/check.py` lints both, and `markdownlint` checks the Markdown.

## Data

Fixture text is synthetic and dedicated CC0: never copy text from a real paper into this repository.
Every file is canonical JSON; never edit a generated file by hand.