- Set up your development environment (see §2 Development Environment Setup). Ensure environment variables are set if using system packages or conda.
- Follow existing module organisation; large viewer subsystems live under
ui/shell/src/<area>/. Under winit 0.30 the desktop entry points are ViewerLoop::{window_event, device_event, about_to_wait} (ui/shell/src/viewer_loop/runtime/runner.rs), driven by event_loop.run_app in ui/shell/src/runner.rs. When adding new functionality, prefer a dedicated module over expanding those handlers.
- Error handling uses
anyhow::Result at the binary/application level and typed thiserror::Error enums inside core crates.
- Avoid
unwrap()/expect() in production paths; prefer early Result returns or explicit fallbacks. Core crates deny clippy::unwrap_used/clippy::expect_used, while tests may allow them when a panic is the expected outcome.
- Instrument long-running tasks with
tracing::instrument where span context helps diagnose renderer, parser, selection, or background-worker behavior.
- Keep documentation up to date: public APIs must have doc comments, and significant behavioural changes should be reflected in the user guide and this guide.
scripts/check-rust-lints.sh is the authoritative lint entry point. It runs general workspace checks plus stricter production-target checks; do not add broad lint allowances to bypass it.
12.1 Error Handling Patterns
- Use
anyhow::Context at CLI/UI boundaries so errors report the path or operation that failed.
- Prefer typed errors in core crates (
IoPipelineError, EditError, etc.) and convert to anyhow only at edges.
- Treat optional parse fields as
Option<T> and log/record warnings rather than panicking on missing data.
- For malformed input, return
ParseError { path, message } with enough detail to debug fixtures.
- Avoid
unwrap/expect in non-test code; use ?, ok_or_else, or a documented fallback.
- The production-target Clippy pass denies
unwrap_used and expect_used. Tests may use panic helpers when failure should abort the test.