35 lines
1.8 KiB
Markdown
35 lines
1.8 KiB
Markdown
# 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.
|