Skip to content

Contributing

  1. Run the checks; they must report OK:

    Terminal window
    pip install -r tools/requirements.txt # optional, enables schema validation
    python3 tools/check_spec.py
    python3 tools/example_links.py # must leave the Markdown unchanged

    After a change to tools/, also run its tests:

    Terminal window
    pip install -r tools/tests/requirements.txt
    python3 -m coverage run --branch --source=tools --omit='tools/tests/*' -m pytest tools/tests -q
    python3 -m coverage report -m
  2. Add a line under [Unreleased] in the changelog.

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.

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.
  • 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. Run python3 tools/example_links.py after adding a scenario or test contract.
  • 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 pyyaml and jsonschema installed: 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. The invalid/ contracts need real tooling and are not checked here, except the contracts over several files.