Documentation

Continuous integration

GitHub Actions owns triggers, permissions, runners, caches, artifacts, matrices, and job dependencies. The justfile owns validation commands so each CI command also runs from a checkout.

Pull requests

The required workflow runs these job groups:

  • source: Rust formatting, cargo check, Clippy, and dependency policy
  • automation: repository hooks and workflow validation
  • contracts: snapshots, the release plan, and Cargo discovery of publishable packages
  • semver: public API compatibility for each publishable package
  • platform: platform-boundary tests on macOS and Windows
  • coverage: the native workspace suite with all features
  • frontend: native and Wasm browser coverage
  • docs: rustdoc, Markdown, Mermaid regeneration, and the site build

The coverage jobs reject uncovered source lines. ci-gate gives branch protection one check name and fails unless every required job succeeds.

CodSpeed runs the ecosystem benchmark packages on standard GitHub-hosted runners in simulation mode. This avoids quota-limited Macro Runners. Run the same benchmark path with just codspeed PACKAGE.

Test synchronization

Tests wait for observable state changes. Child-process cases use ProcessHarness::spawn_until_event, Node::await_event, or the topology event stream. In-process async cases use channels or tokio::sync::Notify. Code that measures elapsed time uses Tokio's paused clock. Deadlines bound failed waits, and the CI profile supplies a per-test termination guard.

Nightly analysis

The nightly workflow runs feature combinations, direct dependency lower bounds, Miri, Loom, AddressSanitizer, mutation testing, each cargo-fuzz target, and the live PyPI client boundary. Each matrix leg invokes a public Just recipe.

Sanitizer and mutation jobs build Nextest archives once, then run partitions from those archives. AddressSanitizer follows Rust's -Zsanitizer and -Zbuild-std invocation. Nextest 0.9.143 classifies Rust's gnuasan target as a custom target, but Rust does not publish custom target JSON for that built-in target. The workflow uses the standard Linux target.

The async suite does not run under ThreadSanitizer. Tokio issue 7299 records internal false positives and identifies Miri and Loom as its race-analysis tools; nightly CI runs both.

Local commands

Install the locked tools, then run the recipe named by a CI job:

mise install --locked
just lint
just platform-test
just coverage-native
just frontend-deps
just coverage-frontend
just docs

Browser recipes install their checksum-verified Chrome for Testing revision from the scoped browser mise environment. Chrome for Testing ships no Linux ARM or Windows ARM builds, so mise.browser.lock covers the four platforms it does publish.

just test is hermetic. just storage-s3 and just coverage-native require a running Docker daemon for the MinIO boundary tests.

Nightly commands are local too:

just features
just direct-minimum
just miri
just loom
just sanitizer-address
just mutation-baseline
just mutation 1/8
just fuzz peryx-ecosystem-oci oci_reference 60
just e2e-live

Generated files stay under .tox/. just coverage-clean, just clean, and just clean-all remove increasing amounts of local build state.

On this page