paperspec/CONTRIBUTING.md

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/paperspec.

What a change needs

A change starts in the chapter of the specification that defines the rule, because the chapters are normative. The schemas, SQL, registries, vectors and fixtures then follow the chapter (spec/00 §0.5).

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.
3. Compute, never type, the expected values. <<<<<<< HEAD Change the oracle in src/paperspec/ to apply the rule, and add the case that shows it to src/paperspec/cli/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, install the checkout with pip install -e ".[tools]" on Python 3.14, then run paperspec check.
5. Record the change in 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). 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, the node schema, and its entry in the CHILDREN table of src/paperspec/model.py. A run kind needs its row in section 3.5 and the node schema, and its text in the plain projection (3.6) and in the strict and lossy projections (5.3, 5.5).

Releasing

A release is a tag vX.Y.Z on main, and its version is the version of the Python package paperspec, which setuptools-scm reads from the tag. A release that changes the formats takes the new format version, which becomes the top heading of CHANGELOG.md and the version that pixi.toml and the registries state. A release that changes only the code takes the next patch version and records it as a subsection under the current format version, as ### 0.1.1 sits under ## 0.1.0. Pushing the tag publishes the package to the Gitea package registry (deploy/). Before tagging:

1. pixi run check passes on Linux and macOS, which the workflow in .gitea/workflows/ runs on every push. The check also confirms that every count the prose states (formats, schemas, vectors, broken packages) matches the repository, and that pixi.toml, the registries and src/paperspec/cli/build.py state the same version.
2. paperspec stress passes with its default seed, and with one or two others.
3. The website is published from the release (deploy/), and the JSON-LD context at https://paperspec.scient.ing/context/scienting-1.jsonld and a schema at its $id both answer with their media types. Layers claim to be W3C Web Annotations, and a JSON-LD processor that cannot fetch the context cannot read them.
4. The decisions that freeze on release are made: enumeration values and format identifiers never change meaning afterwards (spec/22 §22.5), so a name worth changing is changed now.
5. The CHANGELOG entry describes the release in the terms of the chapters it touches.

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 gives it: prose CC-BY-4.0, the normative data CC0-1.0, and the code in src/ and tools/ Apache-2.0. ||||||| parent of 4fa326d (First implementation (#1))

Change the oracle in tools/oracle/ to apply the rule, and add the case that shows it to 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.

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). 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, 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 and the node schema, and its text in the plain projection (3.6) and in the strict and lossy projections (5.3, 5.5).

Releasing

A release is a tag on main whose version is the top heading of CHANGELOG.md. Before tagging:

1. pixi run check passes on Linux and macOS, which the workflow in .gitea/workflows/ runs on every push. The check also confirms that every count the prose states (formats, schemas, vectors, broken packages) matches the repository, and that pixi.toml, the registries and tools/build.py state the same version.
2. python3 tools/stress.py passes with its default seed, and with one or two others.
3. The website is published from the release (deploy/), and the JSON-LD context at https://paperspec.scient.ing/context/scienting-1.jsonld and a schema at its $id both answer with their media types. Layers claim to be W3C Web Annotations, and a JSON-LD processor that cannot fetch the context cannot read them.
4. The decisions that freeze on release are made: enumeration values and format identifiers never change meaning afterwards (spec/22 §22.5), so a name worth changing is changed now.
5. The CHANGELOG entry describes the release in the terms of the chapters it touches.

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 gives it: prose CC-BY-4.0, the normative data CC0-1.0, and tools/ Apache-2.0.

4fa326d (First implementation (#1))