Contributing
Before you open a pull request
Section titled “Before you open a pull request”-
Run the checks; they must report OK:
Terminal window pip install -r tools/requirements.txt # optional, enables schema validationpython3 tools/check_spec.pypython3 tools/example_links.py # must leave the Markdown unchangedAfter a change to
tools/, also run its tests:Terminal window pip install -r tools/tests/requirements.txtpython3 -m coverage run --branch --source=tools --omit='tools/tests/*' -m pytest tools/tests -qpython3 -m coverage report -m -
Add a line under
[Unreleased]in the changelog.
Layout
Section titled “Layout”| Path | Contents |
|---|---|
spec/overview.md, spec/contract.md, spec/core.md |
What applies everywhere |
spec/contract-1.0.0.schema.json |
JSON Schema of the contract format |
spec/profiles/ |
One profile per layer (from slice 1, one slice per profile) |
spec/generators.md |
What a generator must document; generators themselves live in their own repositories (slice 10) |
docs/ |
Tooling overview (informative) |
GOVERNANCE.md |
Roles, decisions, versions and conformance |
site/ |
The site at rialto.buijs.dev, built from the Markdown of this repository |
examples/shipment/ |
The one example every document draws from (grows with the slices) |
examples/contracts/ |
Shared test contracts every implementation must validate the same way |
tools/check_spec.py |
Consistency checks |
tools/conformance.py |
Runs a tool over the shared test contracts |
tools/compare_tools.py |
Compares the findings of two tools over the test contracts, by code, pointer and requirement |
tools/example_links.py |
Writes the Examples: lines under the requirement groups |
tools/tests/ |
Tests of the tools (pytest) |
A profile has the sections Purpose, Example, Terms, Contract, Capabilities, Requirements and Rationale, in that order. Extra sections may be added after Terms and before Capabilities.
Requirements
Section titled “Requirements”Write a requirement as a list item starting with its identifier:
- **M2.4** A generator MUST …| Prefix | Document | Prefix | Document |
|---|---|---|---|
| C | core | P | persistence |
| K | contract | Q | query |
| A | events | R | REST |
| D | domain | S | auth |
| E | errors | U | presentation |
| L | lifecycle | V | versioning |
| M | mapping |
- Identifiers are stable. Never reuse a removed one; a split requirement gets a letter suffix.
- Key words (MUST, SHOULD, MAY, and their NOT forms) are capitals, and only inside requirements.
- An obligation on generators reads “A generator MUST document …”.
- Capabilities are named
<profile>.<name>and refer only to requirements of their own profile. - A deliberate choice, or a rejected alternative, goes into the Rationale section of its document: one to three lines saying why.
Writing style
Section titled “Writing style”- No history, no references to earlier projects or specific runtime libraries.
- Write “and” or “or” instead of a slash; use a list or table for more than three items.
- Add a MUST NOT only for a pitfall the positive rule does not already exclude.
- Use “binding” only as field binding, operation binding or protocol binding (as CloudEvents defines it).
- Implementation status and known gaps belong in the implementation’s repository.
- Every requirement group shows its use: a line
Examples:under its heading links to the Shipment scenarios and test contracts that exercise it. Runpython3 tools/example_links.pyafter adding a scenario or test contract.
What the checks cover
Section titled “What the checks cover”- Requirement identifiers: unique, correct prefix, and every reference resolves.
- Key words inside requirements: no lowercase or mixed case.
- Capability tables: naming and references.
- Terminology: “binding” and forbidden names.
- Links and anchors.
- The checks cover the documents and examples that exist; a reference to a requirement of a profile that has not arrived yet is accepted.
- With
pyyamlandjsonschemainstalled: the Shipment contract (once it is there),examples/contracts/valid/and every YAML block in the Markdown whose keys are contract sections, against the JSON Schema. Start a YAML block that is not a contract, such as a lock file, with# rialto.lock. Theinvalid/contracts need real tooling and are not checked here, except the contracts over several files.