Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
209 lines (140 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

209 lines (140 loc) · 10.1 KB
Raw

Contributing to Provability-Fabric

Thank you for your interest in contributing. This document covers how to get started, run tests, and submit changes. For governance, RFC process, and voting, see the Community Governance guide.

License and conduct

For security vulnerabilities, use the process in SECURITY.md (private report; do not file a public issue first).

How to contribute

  1. Fork the repository and create a feature branch.
  2. Build and test (see below) so your changes do not break the project.
  3. Document any user-facing or config changes.
  4. Submit a pull request with a clear description and reference to any related issues.

For the full pull request and review process, see Governance - Pull Request Process.

Building the project

Minimal (CLI and bundles only)

If you only need the CLI and spec/bundle workflow (no Rust, Node, or Docker):

git clone --recurse-submodules https://github.com/SentinelOps-CI/provability-fabric.git
cd provability-fabric
make dev-standards   # CERT-V1 + TRACE-REPLAY-KIT for evidence/replay tests
# Requires Go 1.23+ (see core/cli/pf/go.mod)
cd core/cli/pf && go build -o pf . && cd ../../..
# Add the binary to your PATH; on Windows the output is pf.exe

Optional: build the specdoc CLI if present:

[ -f cmd/specdoc/main.go ] && cd cmd/specdoc && go build -o specdoc . && cd ../..

Go workspace (local dev)

The repo has many go.mod files. For local multi-module work, copy the workspace template:

cp go.work.example go.work   # go.work is gitignored for local overrides
go work sync                 # optional: align sums after module changes

Primary CLI entrypoint remains core/cli/pf; go.work wires replace paths across modules without manual replace edits in each module.

Standard (CLI + Rust workspace)

Build the CLI as above, then build the Rust workspace (requires Rust and rust-toolchain.toml):

cargo build --workspace

Optional crates (e.g. egress-firewall, core/sdk/rust) may need extra dependencies; see root Cargo.toml comments. Build them separately when needed.

Full (all components)

Run the installation script for your platform:

  • Linux/macOS: ./scripts/install.sh (or ./scripts/install.sh --full for full mode)
  • Windows: scripts\install.bat (or with INSTALL_MODE=full)

See Reuse and extend for install modes (minimal, standard, full) and tiered setup.

Running tests

Windows development (WSL required)

Native Windows (PowerShell/cmd) supports a subset of the dev workflow. Linux CI remains authoritative.

Task Windows native WSL / Linux
Go CLI (core/cli/pf) Pass — go test ./... Pass
Rust workspace (non-excluded crates) Pass Pass
Evidence validate/pack (pf evidence) Pass (static paths) Pass
Evidence replay execute, bash testbeds Skip — needs bash + submodules Pass
make evidence-verify, make test Use WSL or Git Bash Pass
SWE-bench real engine Skip Pass with OpenHands
Lean / Lake builds Use WSL Pass
Full platform docker compose Partial Pass

Recommendation: Install WSL2 with Ubuntu, clone the repo inside the Linux filesystem (~/provability-fabric), and run bash/Makefile targets from WSL. Git Bash works for light gates (make evidence-verify subset) but not for Lean/Lake or full integration tests.

Quick Windows smoke (no WSL):

cd core\cli\pf; go test ./...
cargo test --workspace --exclude sidecar-watcher --exclude labeler --exclude tool-broker

Full parity subset via Makefile:

make test-windows   # CLI + Rust smoke; skips Linux-only paths

Minimal checks

  • CLI version: ./pf --version (or pf.exe --version on Windows) from the repo root after building the CLI.
  • CLI unit tests: From core/cli/pf, run go test ./...

Standard (plus Rust)

From repo root:

cargo test --workspace --exclude sidecar-watcher
cargo test -p sidecar-watcher --lib
cargo test -p sidecar-watcher --tests
# Clippy (full workspace): cargo clippy --workspace -- -D warnings

sidecar-watcher uses autotests = false and explicit [[test]] entries for integration binaries that compile; other sources under runtime/sidecar-watcher/tests/ are quarantined until updated (see runtime/sidecar-watcher/tests/README.md). CI runs --lib and --tests (see .github/workflows/reusable-ci-rust.yml).

Full test suite

From repo root:

python tests/trust_fire_orchestrator.py
# Integration: python tests/integration/test_platform_integration.py
# See Makefile: make test

Install Python dependencies as needed (e.g. pip install -r tests/integration/requirements.txt). Minimal install does not need Python tooling; for full dev run pip install -r requirements-optional.txt (see root requirements-optional.txt).

Evidence and CI

Evidence changes should pass the evidence-v01-smoke.yml workflow on Linux CI. Before opening a PR that touches specs/evidence/**, core/evidence/**, testbed scripts, or related tests:

make dev-standards   # CERT-V1 + TRACE-REPLAY-KIT submodules
make evidence-verify # Go tests, pytest suites, v0.1 + v0.2 testbed scripts
make docs-strict     # mkdocs build --strict (docs-only PRs)

make evidence-verify requires bash (Linux, WSL, or Git Bash on Windows). Clone external standards per external/README.md.

STANDARDS_GITHUB_TOKEN (org admin)

CI workflows that call make submodules need a repository secret so GitHub Actions can clone private standards repos (verifiable-ai-ci/CERT-V1, verifiable-ai-ci/TRACE-REPLAY-KIT). Org admin must add the secret; contributors cannot self-serve it on the upstream org repo.

  1. Create a fine-grained PAT (or classic PAT) owned by a bot/service account with read access to verifiable-ai-ci/CERT-V1 and verifiable-ai-ci/TRACE-REPLAY-KIT.
  2. In GitHub: Settings → Secrets and variables → Actions → New repository secret.
  3. Name: STANDARDS_GITHUB_TOKEN, value: the PAT.
  4. Verify locally (with the same token exported): STANDARDS_GITHUB_TOKEN=<pat> make dev-standards.
  5. Verify in CI: re-run Standards Pin Drift Check or Evidence v0.1 smoke via workflow_dispatch; the make submodules step should succeed in the log.

Workflows using this secret are listed in CI health matrix — Required secrets. Forks without the secret can still run most gates; standards/replay jobs fail until the secret is configured or submodules are vendored locally.

See Evidence v0.2 delivery guide for the fresh-clone checklist and Evidence v0.2 status for current delivery gates.

CI expectations

Change type Required local checks CI workflows
Evidence / standards make evidence-verify evidence-v01-smoke.yml, standards-pin.yml
Docs only make docs-strict docs-build.yaml, docs-deploy.yaml
Code (general) go test, cargo test, targeted pytest ci.yml reusable jobs

Repo-wide triage and known failures: CI health matrix. Do not admin-merge while required checks are red (see CI policy below).

CI policy

  • No admin merge on red: merge only when all required status checks for the PR scope are green. Document any exception in the PR body and update the health matrix. Branch protection on main enforces CI required checks, smoke, evidence-schema-only, and Documentation Build (applied 2026-06-16).
  • Local gates before CI PRs: make dev-standards, make evidence-verify (evidence paths), make docs-strict (docs), make proto-lint proto-validate (protobuf).
  • Inventory: run scripts/ci_workflow_inventory.sh (Linux/macOS/WSL) or scripts/ci_workflow_inventory.ps1 (Windows) on main after large workflow changes; see CI health matrix.

Local pre-commit gates (Wave 0 / F36)

Install pre-commit and enable hooks once per clone:

pip install pre-commit
pre-commit install
pre-commit run --all-files   # optional full sweep

Hooks mirror critical CI checks: actionlint on workflow files, placeholder scan (scripts/check_no_placeholder.py), trailing-whitespace/YAML hygiene, gofmt, and cargo fmt. See .pre-commit-config.yaml. On Windows without bash, run pwsh scripts/ci_workflow_inventory.ps1 and targeted pytest/jest commands before opening a PR.

Reuse and forking

If you are forking the repo to build your own product or variant, see the Reuse and extend guide. It covers:

  • Minimal vs standard vs full setup
  • What to rename or configure when forking (branding, URLs)
  • Adding adapters and bundle templates
  • Fork-friendly configuration

Documentation

Questions

  • GitHub Issues: Bug reports and feature requests.
  • GitHub Discussions: General questions and ideas.
  • Governance: Community Governance for RFCs, working groups, and decision-making.