Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
62 lines (46 loc) · 2.5 KB

CONTRIBUTING.md

File metadata and controls

62 lines (46 loc) · 2.5 KB
Raw

Contributing to churn

Thanks for your interest in churn! The core is zero-GPU and runs on a laptop, so almost everything here is contributable without special hardware.

Ground rules

  • Determinism is an invariant, not a feature. Same seed + scenario ⇒ byte-identical trace. Every change must preserve this. It is enforced by a property test and committed golden traces — if your change alters traces, the golden diff will fail, and that failure is the design talking to you. Regenerate goldens only when the change is intended to alter behaviour, and call it out in the PR.
  • Mechanism vs. policy. The engine (crates/churn-core) owns time, membership, network, and events. A Policy owns only the round decisions. New behaviour usually belongs behind the Policy trait, not in the engine.
  • Relative truth before absolute truth. We model time, membership, and coordination — not tensors. New results are meaningful as A/B deltas on identical seeds.

Getting set up

# Rust core
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

# Python wheel
python3 -m venv .venv && . .venv/bin/activate
pip install maturin pytest
maturin develop
pytest python/tests/

The integration/ directory (real torch.distributed/gloo validation) has its own .venv and is outside the cargo workspace, the wheel, and the CI gate — see integration/README.md for its setup.

Before you open a PR

Run the full local gate — it mirrors CI:

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
maturin develop && pytest python/tests/
  • Keep PRs focused; one logical change per PR.
  • Add or update tests for behaviour you change. New policies/scenarios should come with a golden trace.
  • If you touch timing/network/membership, say in the PR whether goldens changed and why.

Good first areas

  • New scenarios — especially partitions and jittery stragglers that exercise median + k·MAD rather than the min_deadline floor.
  • Parameter-sweep tooling (v1.2) — map where StragglerPolicy helps, breaks even, or hurts.
  • Plotting helpers (v1.3) — arrival/stall timelines, baseline-vs-straggler bars.

See ROADMAP.md for the bigger picture and the highest-impact open work.

License

By contributing, you agree that your contributions will be dual-licensed under the Apache-2.0 and MIT licenses, as described in the README, without any additional terms or conditions.