# 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 `pixi run build` to regenerate the vectors and fixtures, and commit the regenerated files with the change.
`pixi run check` must pass.
Without pixi, run `python3 tools/build.py` and `python3 tools/check.py`, and lint the Markdown with markdownlint-cli2.

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.

## The environment

`pixi.toml` pins the development environment: Python, the `jsonschema` package and markdownlint-cli2, from conda-forge.
Commit `pixi.lock` whenever pixi updates it, so that CI and every contributor solve the same environment.
`pixi run -e py310 check` runs the checks on the oldest supported Python.
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 explain any rule that a reader may question in [docs/rationale.md](docs/rationale.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 `pixi run lint` checks the Markdown with markdownlint-cli2.

## 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.