|
| 1 | +# Contributing |
| 2 | + |
| 3 | +This is an early release of part of our robotics stack. Feedback and issue reports |
| 4 | +are welcome. |
| 5 | + |
| 6 | +For development, follow [source setup](docs/getting-started.md#from-source), then |
| 7 | +run `uv sync --locked` from the checkout root. The pinned Rust toolchain includes |
| 8 | +Clippy and rustfmt. Python checks run on 3.14; the package supports Python 3.12+. |
| 9 | +Python dependencies keep a three-day minimum release age. |
| 10 | + |
| 11 | +For Python changes: |
| 12 | + |
| 13 | +```sh |
| 14 | +uv run ruff check --fix |
| 15 | +uv run ruff format |
| 16 | +uv run ty check |
| 17 | +uv run pytest |
| 18 | +``` |
| 19 | + |
| 20 | +For Rust changes: |
| 21 | + |
| 22 | +```sh |
| 23 | +cargo fmt |
| 24 | +cargo clippy --all-targets --all-features |
| 25 | +cargo test --workspace --all-features |
| 26 | +``` |
| 27 | + |
| 28 | +Check documentation links with `lychee --offline -v .`; use `lychee -v .` to |
| 29 | +include external links. CI checks Python and Rust on Ubuntu 24.04. |
| 30 | + |
| 31 | +The media build needs the prerequisites in [camera setup](docs/cameras.md). |
| 32 | +Keep credentials, recordings and per-arm calibration out of commits. |
| 33 | + |
| 34 | +For camera changes, verify a real USB or phone stream with LiveKit: browser |
| 35 | +video, SDK snapshots, simultaneous readers, reconnection and shutdown. Simulator |
| 36 | +checks do not cover a physical camera or arm. |
| 37 | + |
| 38 | +## Code style |
| 39 | + |
| 40 | +- Use descriptive function and variable names, even when they are verbose. |
| 41 | +- Prefer explicit types and typed variants; make invalid states hard to represent. |
| 42 | +- Use exhaustive matching where practical, and parse external values at boundaries. |
| 43 | +- Share internal operations instead of duplicating behavior across entry points. |
| 44 | +- Preserve and log unknown external values when the boundary permits recovery. |
| 45 | +- Comment on non-obvious decisions rather than restating the code. |
| 46 | +- Test observable outcomes and real business logic, not mocks or library internals. |
| 47 | +- Use uv for Python. Keep changes scoped and run targeted checks first. |
| 48 | + |
| 49 | +Use the workspace's existing Clippy allowances and Python lint settings. The |
| 50 | +release uses `panic = "abort"`; default test builds retain unwinding. Configure |
| 51 | +sccache in your own Cargo settings rather than requiring it for contributors. |
0 commit comments