# Contributing

This page is for anyone who wants to fix the specification, change a format or add an example.
Propose a change as a pull request on the repository at <https://git.scient.ing/infra/manuspec>.

## What a change needs

A change starts in the chapter of [the specification](spec/README.md) that defines the rule, because the chapters are normative.
The schemas, SQL, registries, vectors and fixtures then follow the chapter ([spec/00 §0.5](spec/00-introduction.md#05-how-the-repository-is-arranged)).

1. **Change the chapter.**
   Say what is new in the chapter's own terms, and link the sections it touches.
2. **Change the schemas, SQL and registries** that the rule shapes.
   A new refusal gets a rule ID in [registry/rules.json](registry/rules.json).
3. **Compute, never type, the expected values.**
   Change the oracle in [tools/oracle/](tools/oracle/) to apply the rule, and add the case that shows it to [tools/build.py](tools/build.py): a vector, a fixture or a broken package in `fixtures/invalid/`.
   Then run `pixi run build`, which rewrites `fixtures/` and `vectors/`.
4. **Run the checks.**
   `pixi run check` must end with `All checks pass.`
   Without pixi, run `python3 tools/check.py`, with Python 3.14 and two packages, `jsonschema` and `cryptography` installed.
5. **Record the change** in [CHANGELOG.md](CHANGELOG.md).

## Versions

A change that makes a valid file invalid, or that changes a computed value, is a breaking change and needs a new major version of the format, with a migration.
Adding an optional property, a node kind, a run kind or an enumeration value is a minor change ([spec/00 §0.3](spec/00-introduction.md#03-format-identifiers-and-versions)).
A rebuild that changes any file under `vectors/` or any hash in `fixtures/` is a computed value changing, so say in the pull request why it must.

## New node kinds and run kinds

Propose a kind with the vector or fixture that shows it.
A node kind needs its row in [chapter 3](spec/03-nodes.md), the node schema, and its entry in the `CHILDREN` table of `tools/oracle/model.py`.
A run kind needs its row in [section 3.5](spec/03-nodes.md#35-inline-runs) and the node schema, and its text in the plain projection ([3.6](spec/03-nodes.md#36-the-plain-projection)) and in the strict and lossy projections ([5.3](spec/05-hashes.md#53-the-strict-projection), [5.5](spec/05-hashes.md#55-the-lossy-projection)).

## Writing

The checker enforces two rules on every Markdown file: one sentence per line, and US spelling.
`pixi run lint` runs markdownlint with the repository's settings.
Define each term where it first appears, because the guides and READMEs are written for newcomers as well as implementers.

All fixture text is synthetic, written for the fixtures.
The keys in `fixtures/keys/` are public test keys and must never sign anything else.

## Licenses

Each path keeps the license that [LICENSE.md](LICENSE.md) gives it: prose CC-BY-4.0, the normative data CC0-1.0, and `tools/` Apache-2.0.