Contributing

Thank you for your interest in improving QuantaBox. This guide covers how the project is organized, the conventions to follow, and how to submit changes.

Project Layout #

QuantaBox is a Cargo workspace plus a Tauri app. See Components for the crate breakdown and Architecture for how they fit together. Build instructions are in Building from Source.

Before You Start #

• Open or comment on an issue describing the change, especially for anything user-visible or architectural, so the direction can be agreed before you invest time.
• Keep pull requests focused -- one logical change per PR is easier to review and revert.

Coding Conventions #

Rust

• Target the stable toolchain, 2021 edition.
• Format with cargo fmt and keep cargo clippy clean.
• Prefer anyhow::Result for fallible application code; return precise errors.
• All subprocess spawns must use the no_console() helper so the GUI never flashes a console window on Windows. See Components -- the proc helper.
• Keep platform-specific code behind #[cfg(target_os = "...")] and provide a sensible fallback for other platforms.

Frontend (GUI)

• Svelte 4 + TypeScript + Tailwind CSS.
• Keep Tauri commands thin -- push real logic into quantabox-core so the CLI benefits too.
• Production builds must keep the custom-protocol feature intact (see Building from Source).

Documentation

• User-facing docs live under docs/. Match the existing structure and the lightweight YAML frontmatter (title, description, order).
• Document features as they actually behave; do not describe unimplemented behavior as if it exists.

Testing #

Add or update tests for the code you change. Run the suite before submitting:

cargo test --workspace

For GUI changes, verify a production build runs (not just tauri dev):

cd gui && cargo tauri build --bundles none

Commit and PR Workflow #

1. Branch from the default branch.
2. Make your change with clear, scoped commits.
3. Ensure cargo fmt, cargo clippy, and cargo test --workspace all pass.
4. Open a pull request describing what changed and why, linking any related issue.
5. Respond to review feedback; keep the branch up to date with the base.

Licensing #

QuantaBox is dual-licensed under Apache License 2.0 and GNU General Public License v2.0. By contributing, you agree your contributions are provided under these terms. Include the standard SPDX header on new source files:

// SPDX-License-Identifier: Apache-2.0 OR GPL-2.0
// Copyright (c) 2024 Dyber, Inc.

Security #

Do not report security vulnerabilities through public issues. If you discover a vulnerability -- especially anything touching the cryptography, key vault, or VM isolation -- disclose it responsibly:

1. Email the security contact at security@dyber.org (or the address published at dyber.org).
2. Include a description, reproduction steps, and impact assessment.
3. Allow reasonable time for a fix before any public disclosure.

Questions #

Open a discussion or issue on the project repository. Thanks for contributing to QuantaBox!

Quick Reference #