1.8 KiB
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, and explain any rule that a reader may question in 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.