Contributing

The one rule

The conformance suite is the specification. A change to behaviour changes the specification, the reference implementation, the conformance cases and every runtime, in one pull request. Where the prose and the suite disagree, the suite wins and the prose is a bug.

Prerequisites

Verifying a change

make verify

runs what CI runs, except the Maven builds, the React example build, the Docker image and the other operating systems. It needs all four toolchains. Each part is a target of its own:

Not part of verify:

The examples in examples/backend-node, examples/backend-go, examples/batch and examples/agent-tools have their own tests, which CI runs in one job each:

npm run build && npm run test:examples                    # Node.js service and agent tools
(cd examples/backend-go && go test ./...)                  # Go service
python -m unittest discover -s examples/batch -v           # batch recipe, on every engine that is built
(cd packages/go && GOTOOLCHAIN=go1.22.12 go test ./...)    # the Go runtime on its declared minimum

A passing suite ends with conformance: 1899 cases, 0 failure(s), for every engine.

Changing the specification

Work in this order. Each step has something to run before the next.

1. Specification and schema. Edit spec/v1/SPECIFICATION.md. For a change to the shape of a ruleset, edit spec/v1/rule-cascade.schema.json, and only that copy. For a change to the wire API, edit spec/v1/rule-evaluation.openapi.yaml.
2. Reference implementation. Implement it in packages/python/src/rule_cascade: expressions in expressions.py, loading in ruleset.py, evaluation in evaluate.py, the protocol in engine.py.
3. Conformance cases. Add hand-written cases that pin the behaviour down, including the errors: conformance/expressions.json, load-errors.json, protocol.json. For behaviour that needs a whole ruleset, add golden tests to an example ruleset or to a ruleset in conformance/sources.
4. Regenerate. python tools/rulecheck.py sync copies the schema into the four packages and regenerates fixtures, bundles, expectations and the evaluation corpus. Read the diff: an unexpected change there is a behaviour change. Then make contract conformance python.
5. Every runtime. Port the change to packages/typescript, packages/java and packages/go and run each suite in process: make typescript java go.
6. The driver. make go-release engines certifies every engine, the WebAssembly module included, over the engine protocol.
7. Everything that describes it. CHANGELOG.md; the package READMEs; docs/; for a new operator also the op enum in bindings/rule-draft.response-format.json, which tools/lint_specs.py compares with the schema. A significant design choice gets an ADR in docs/adr/.

Common changes:

Adding a runtime in a new language

Start at the evaluator level (specification section 11). It needs a JSON parser, decimal arithmetic with 34 significant digits and a regular-expression engine, and no YAML and no JSON Schema.

1. Expressions (section 4): literals, var, the 45 operators, function calls, custom operators, and the scanner for portable patterns (4.4). conformance/expressions.json has 499 cases.

2. Bundles and evaluation (sections 7 and 8): read a bundle, select rules, run the phases, produce findings, effects and commands. Check the shape of a request before evaluating.

3. The engine protocol (section 13): a program that reads one JSON request per line and writes one response per line, with version, load, manifest, evaluate and expression. Answer compile with UNSUPPORTED and report the level evaluator. Register the three conformance operators of conformance/README.md behind an option.

4. Certify it with the driver, and fix what it reports:

   PYTHONPATH=packages/python/src python tools/rulecheck.py conformance \
     --engine "<your command> engine --conformance-operators"

   The driver skips the compiler-level cases for an engine that does not report the level compiler. An evaluator runs 1683 cases. Four of them are compile cases in conformance/protocol.json that the driver does not skip yet; an engine that answers compile with UNSUPPORTED fails exactly those four until it reaches the compiler level.

5. Make it part of the repository: a package under packages/<language> with a README, a test that runs the suite in process, a Makefile target, a line in make engines, a CI job on the three operating systems, and an entry in docs/languages.md.

The compiler level comes second: schema validation, inheritance, the load-time checks, the checksum and the manifests (sections 5 to 7), certified by the load-error cases and by producing exactly the published bundles. A language that only needs to enforce rules never needs it: bundles are compiled in CI by any existing compiler.

A language that needs neither a library nor a port uses the rule-cascade command or the WebAssembly module; see examples/engine-clients.

Generated files

Do not edit these by hand. python tools/lint_specs.py and python tools/rulecheck.py sync --check fail when one is stale, and .gitattributes marks them as generated so that diffs collapse them. Review their diffs all the same.

make sync is python tools/rulecheck.py sync. Build output (dist/, target/) is not committed.

Pull requests

• Branch: <type>/<short-description>, for example feat/date-operators.
• Commits: Conventional Commits. The types in use are feat, fix, refactor, chore, ci and docs. The scope is the area: spec, conformance, python, typescript, java, go, server, tools, examples, docs. Mark a breaking change with !, as in feat(spec)!: ....
• A change that spans runtimes is one pull request with one commit per area: the specification, reference and conformance cases first, then each runtime.
• One logical change per pull request. CI must be green.
• Anything a user can observe goes in CHANGELOG.md, in the section of the version in progress.
• Significant design choices get an ADR in docs/adr/.
• Use the checklist in .github/pull_request_template.md.

Names for rulesets, rules, codes, files and packages are in docs/naming-conventions.md. How to write rulesets is in docs/authoring-guidelines.md.

Compatibility

While the specification is a draft (1.0.0-alpha.N), these promises describe the intent for 1.0; alpha versions may break, and the changelog says where.

Rendered from CONTRIBUTING.md in the repository. Edit it there.