Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
117 lines (86 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

117 lines (86 loc) · 3.5 KB
Raw

Contributing to QShield

Thank you for your interest in contributing to QShield. This document covers the development setup, coding standards, and pull request process.

Development Setup

Prerequisites

  • Rust 1.74 or later (stable toolchain)
  • Git

Build and Test

git clone https://github.com/jbaelaw/qshield.git
cd qshield

# Debug build
cargo build

# Release build (optimized, stripped)
cargo build --release

# Run all tests
cargo test

# Run linter
cargo clippy --all-targets -- -D warnings

# Check formatting
cargo fmt --check

# Apply formatting
cargo fmt

Project Layout

src/
├── main.rs              # CLI entry point and command handlers
├── crypto/
│   ├── kem.rs           # Hybrid ML-KEM-768 + X25519 encapsulation
│   ├── kdf.rs           # Argon2id and HKDF key derivation
│   └── symmetric.rs     # AES-256-GCM encryption (single-shot + streaming)
├── volume/
│   └── format.rs        # QSV file header serialization
├── tui/
│   ├── app.rs           # Terminal UI state machine
│   └── widgets.rs       # Ratatui UI components
├── error.rs             # Error types
└── ui.rs                # CLI output formatting

Coding Standards

General

  • All code must pass cargo clippy --all-targets -- -D warnings with zero warnings
  • All code must pass cargo fmt --check (uses rustfmt.toml in the repo root)
  • Maximum line width: 120 characters
  • Use thiserror for error types; implement From<std::io::Error> where appropriate

Cryptographic Code

  • All sensitive key material must be zeroized after use via the zeroize crate
  • Never log, print, or serialize key material (even in debug builds)
  • Use OsRng (via rand::rngs::OsRng) for all cryptographic randomness
  • Validate all input sizes before cryptographic operations
  • Prefer constant-time operations for key comparisons

Testing

  • All cryptographic primitives must have roundtrip tests
  • Test error cases (wrong key, corrupted data, truncated input)
  • Use #[cfg(test)] modules within each source file
  • Integration tests should use cargo test and temporary files

Pull Request Process

  1. Fork the repository and create a feature branch from master
  2. Implement your changes following the coding standards above
  3. Test locally: 
    cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check
  4. Commit with a clear, descriptive message explaining why (not just what)
  5. Open a PR against master with:
    • A summary of changes
    • Motivation / context
    • Test plan (what you tested and how)
  6. CI must pass — the PR will be checked by automated tests, clippy, and formatting on Ubuntu, macOS, and Windows

Commit Message Format

<scope>: <concise description>

<optional body explaining motivation and trade-offs>

Examples:

  • crypto: add ML-KEM-1024 support for Level 5 security
  • format: extend QSV header with content type field
  • tui: add disk encryption menu items

Reporting Issues

  • Bugs: Open a GitHub Issue with reproduction steps, expected vs. actual behavior, and your platform/version
  • Security vulnerabilities: See SECURITY.md — do not open a public issue
  • Feature requests: Open a GitHub Issue with a description of the use case

License

By contributing, you agree that your contributions will be licensed under the MIT License.