Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
79 lines (61 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

79 lines (61 loc) · 3.75 KB
Raw

Contributing

ProvableWorldModel is spec-driven. The specification (specs.md, with roadmap.md and backlog.md) is the source of truth; code implements it. Read the relevant specification before writing code, and keep the spec and the code in sync. The pre-pivot STARK corpus is archived under docs/legacy-stark/ and is no longer normative.

Workflow

  1. Every change traces to an issue, and every issue traces to a specification section or an RFC. If the work you want to do is not covered, propose the spec change first (see "Changing the specification").
  2. One issue is one shippable pull request by one contributor in a bounded time. If a change does not fit that, decompose it.
  3. Branch from main. Reference the issue in the pull request. Keep the diff focused on the issue's scope.

Run bash ci/check-local.sh quick while iterating. Before opening or merging a pull request, run bash ci/check-local.sh full; it mirrors the non-external CI gates and fails on the first broken contract. Before tagging, run bash ci/check-local.sh release <version> after preparing the changelog.

Changing the specification

Load-bearing decisions are recorded in specs.md, not in code review. A change that alters a public interface, an on-disk format, the proof semantics, the threat model, the arithmetic, or a cross-cutting contract updates the spec first. Editorial fixes do not.

Proof semantics are versioned. Any change to architecture, quantization, rounding, an approximation, a planner rule, or serialization mints a new relation_id; see specs.md.

Code standards

  • Rust: code must pass cargo fmt --check and cargo clippy -- -D warnings.
  • The verifier crate (pwm-verifier) must build under no_std. Do not add std-only dependencies to it.
  • The verifier must not depend on the export pipeline or on PyTorch.
  • Public items carry doc comments stating preconditions, postconditions, and errors. Source files carry an SPDX-License-Identifier: Apache-2.0 header.
  • Public prose (README, specs, demo docs, changelog, website copy) uses no em dashes; run python3 ci/check-prose-style.py before opening a pull request.
  • Python (export pipeline): keep code type-annotated and pass the pinned Ruff gate with bash ci/check-python-style.sh. The fixed-point reference must match the Rust reference bit-for-bit.

Testing

No component is complete without both accepting tests (valid witnesses verify) and rejecting tests (each enumerated invalid witness is rejected with the correct typed error). See specs.md. New numerical primitives ship with committed golden vectors and stated domain bounds.

Continuous integration gates

A pull request must pass: formatting, clippy -D warnings, the unit and integration test suites, the MSRV build, golden-vector parity (Python integer reference vs Rust integer reference), the no_std float-free verifier build, the documentation build, the release-mode full-dims predictor test, the mutation gate, the Lean proofs, the Python style check, the prose-style check, the script mode check, and the SPDX/license/supply-chain check. See specs.md and the hardening ledger in backlog.md.

The local entry point is bash ci/check-local.sh full. The hosted Real E2E workflow remains separate because it downloads external Hugging Face assets and builds the PyTorch export image.

Security

Do not file public issues for suspected vulnerabilities. See SECURITY.md.

License

By contributing you agree that your contributions are licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.