Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing to Argos

Argos is early-stage; the current state of the project is tracked as a backlog of epics and stories in docs/architecture.md, which also documents the design decisions behind the current crate layout.

Getting set up

  • Install a stable Rust toolchain (1.88+). Via mise: mise use -g rust@latest. Via rustup works too.
  • cargo build --workspace
  • cargo test --workspace
  • Before sending a change: cargo fmt --all and cargo clippy --workspace --all-targets -- -D warnings (this is exactly what CI runs).
  • The write-path integration tests exercise a real file-backed loop device and need root: sudo -E cargo test -p argos-privileged --features test-overrides --test loop_device_write -- --ignored --nocapture. They are #[ignore]d and skip themselves cleanly without root, so the regular cargo test --workspace above never needs it.

Workspace layout

  • crates/argos-core – all platform-agnostic logic (device model, ISO classification, checksums, the write engine). No direct disk/OS I/O; must stay testable with plain files and in-memory buffers.
  • crates/argos-platform – the PlatformOps trait every OS backend implements.
  • crates/argos-platform-linux, crates/argos-platform-macos, crates/argos-platform-windows – OS-specific implementations of that trait. The Windows one is a deliberate stub (out of v1 scope) that exists only to keep the trait honestly cross-platform.
  • crates/argos-privileged – argos-helper, the one binary meant to run as root. Keep it minimal and dumb by design (see the doc comment in its main.rs) – do not add D-Bus or other heavy dependencies to this crate. Scoped exception (backlog #27, decided when W3 landed; the write path itself was replaced by phase 3’s pure-Rust FAT32 layout, decision point M4.3, but the exception still holds for it): the Windows installer write path does read the source ISO’s file tree here, via argos_core::image::windows/cdfs, so it can copy those files onto the freshly-formatted FAT32 partition and hash each one as it goes – in a single privileged elevation, matching every other write path’s UX, rather than splitting the operation across two separate pkexec/sudo prompts or redesigning the one-shot IPC protocol into a stateful one. Don’t take this as license to grow the ISO-parsing surface here further; it’s accepted specifically because the copy step cannot happen anywhere else without one of those two costs.
  • crates/argos-session – UI-agnostic orchestration: resolving and refusing devices, classifying images, running the preflight checks, building the Plan, elevating argos-helper and streaming its events. The seam between what Argos does and how a user is asked about it. It must not print, read stdin, or grow a terminal dependency (ctrlc, indicatif, console and clap all belong to argos-cli) – that is what lets a GUI reuse the exact same safety checks rather than reimplementing them.
  • crates/argos-cli – the argos command-line tool.

Safety-critical code

Anything touching device selection or the write path exists to answer one question: is it safe to write to this disk? Changes to argos_core::device::Device::is_safe_to_write, the platform crates’ enumeration logic, or the privileged helper’s re-validation should:

  • come with tests (unit tests for pure logic, the negative “never write a system disk” suite for anything device-selection related), and
  • err on the side of refusing a device rather than guessing it’s safe.

argos-platform’s test-fixtures feature exposes a FakePlatform, the one place PlatformOps is faked in this project. Its scope is deliberately narrow: it exists to test orchestration – whether prepare_write runs its checks in the right order, whether a front end copes with a device vanishing mid-selection. It is not evidence about device safety. A fake that declares a disk safe proves nothing about the code that decides that, so anything touching enumeration or the safety gate stays tested against real signals, real loop devices and real hdiutil images.

Commit messages

Commit messages are written in English, regardless of the language used in discussion or planning.

License

By contributing, you agree that your contributions will be licensed under either the MIT license or the Apache License 2.0, at the user’s option, as described in LICENSE-MIT and LICENSE-APACHE.