Build Velocity with confidence

This guide is for contributors hacking on Velocity itself—whether you’re tuning the transport, expanding the CLI, or polishing docs.

Repository atlas

adoption/          Partner enablement kits and pilots
benchmarks/        Criterion harnesses, load generators, automation scripts
crates/            Core Rust workspace: client, server, crypto, edge runtime
docs/              Authoritative guides mirrored into this site
examples/          Browser gateway, static file server, JSON API, FFI samples
native-bindings/   C ABI and shims for other runtimes
spec/              Protocol draft, formal models, reference transcripts

Tooling baseline

• Rust stable ≥ 1.81 (rustup override set stable keeps CI happy).
• Node ≥ 20 for the docs site and templating runtime.
• Format + lint before pushing: cargo fmt, cargo clippy --all-targets --workspace, cargo test --workspace.
• Optional but fast: cargo nextest for a tighter feedback loop.

Working model

1. Fork, branch, and run npm install && cargo fetch (or just setup).
2. Keep commits focused; security-adjacent changes need two maintainer reviews.
3. Update docs alongside behaviour changes—this site mirrors curated summaries automatically.
4. Use the existing GitHub Actions workflows as guardrails when adding checks.

Testing strategy

• Unit tests live next to modules under src/.
• Integration tests live in crates/*/tests.
• Fuzzers live under crates/pqq-core/fuzz; run them before changing parsing or crypto.
• Benchmarks reside in benchmarks/; record results when performance-sensitive code moves.

Documentation norms

• Author long-form guides in docs/, then summarise them for this site.
• Include change logs at the top of markdown files so operators see what’s new.
• Store diagram sources under docs/assets/ for easy updates.

Release etiquette

• Tag releases only after CI is green and changelog entries are ready.
• Sign binaries following the process in SECURITY.md.
• Publish release notes with highlights, upgrade steps, and security considerations.