Contributing to Speedwave
Speedwave maintains an open-source development process. Whether implementing bug fixes, extending platform drivers, or enhancing documentation, start by configuring your workstation with the Development setup guide and verifying code quality with Testing and quality gates.
All development tasks are orchestrated via the project Makefile. Executing make setup-dev installs dependencies, make dev launches the desktop application with live reload, and make check-all executes the full continuous integration quality gate (linting, Rust clippy, Angular type checking, unit tests, code coverage, and dependency vulnerability audits). Running cargo or npm commands directly is discouraged to prevent inconsistent build flags across monorepo packages.
Core engineering principles
Section titled “Core engineering principles”The codebase strictly adheres to standard software engineering best practices:
- KISS (Keep It Simple, Stupid): Speedwave acts as an orchestration layer on top of Lima, nerdctl, and containerd. Avoid custom engine implementations when established native tools are available.
- YAGNI (You Aren’t Gonna Need It): Implement features strictly specified in active technical specifications.
- DRY (Don’t Repeat Yourself): Shared logic belongs in
speedwave-runtime(ormcp-servers/shared/for MCP workers). Model catalogs and constants maintain single sources of truth. - SOLID: Runtime abstractions enforce single responsibilities (e.g.
ContainerRuntimedelegates container lifecycle exclusively), enabling platform drivers (LimaRuntime,WslRuntime) to implement the polymorphicLockedRuntimetrait. - Rule of Three: Avoid premature abstractions until design patterns repeat across three distinct subsystems.
Logging and diagnostics
Section titled “Logging and diagnostics”Rust modules route diagnostics exclusively through the log facade crate, strictly forbidding direct println! or eprintln! statements. All log sinks pass through the secret redaction filter (log_sanitizer.rs) prior to writing to disk, standard error streams, or webview IPC layers.
Git hygiene and quality gates
Section titled “Git hygiene and quality gates”- Never bypass pre-commit or pre-push Git hooks.
- Never force-push or merge code bypassing repository branch protection rules.
- Commits must pair implementation changes with corresponding automated tests covering happy paths, edge cases, error handlers, and state machines.
- Failing tests must be remediated immediately; disabled or skipped tests are disallowed.