Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
172 lines (116 loc) · 3.8 KB

CONTRIBUTING.md

File metadata and controls

172 lines (116 loc) · 3.8 KB

Contributing to Harmonia

Development Environment

Enter the development shell:

nix develop

This provides:

  • Rust toolchain (rustc, cargo, rustfmt, clippy)
  • cargo-watch, cargo-nextest, cargo-llvm-cov
  • rust-analyzer for IDE support
  • mold linker on Linux for faster builds

Building

Build the entire project:

cargo build --workspace

Or use Nix:

nix build

Running Tests

Quick iteration with cargo

# Run all tests with nextest (faster, parallel)
cargo nextest run --workspace

# Run a specific test
cargo nextest run --workspace test_name

# Run tests in a specific crate
cargo nextest run -p harmonia-cache

# Watch mode during development
cargo watch -x 'nextest run --workspace'

Full test suite with Nix

# Run unit/integration tests with coverage
nix build .#checks.x86_64-linux.tests -L

# Run NixOS VM tests (Linux only)
nix build .#checks.x86_64-linux.nix-daemon -L
nix build .#checks.x86_64-linux.harmonia-daemon -L

Coverage

Coverage reports are generated automatically in CI. To generate locally:

export LLVM_COV=$(which llvm-cov)
export LLVM_PROFDATA=$(which llvm-profdata)
cargo llvm-cov nextest --workspace --html
# Open target/llvm-cov/html/index.html

Benchmarks

Run the closure download benchmark:

cargo bench --package harmonia-bench

# With verbose output
cargo bench --package harmonia-bench -- --nocapture

This benchmarks downloading a Python closure through harmonia-cache. By default it builds harmonia with the profiling profile (release + debug symbols for flamegraphs).

Environment variables:

  • HARMONIA_FLAKE - Use a nix-built harmonia instead of cargo build
  • BENCH_CLOSURE_FLAKE - Override the benchmark closure (default: .#bench-closure)

View results:

open target/criterion/closure/download/report/index.html

Code Style

Formatting

Format all code before committing:

nix fmt

This runs treefmt which handles:

  • Rust: rustfmt (2024 edition)
  • Nix: nixfmt
  • C/C++: clang-format

Linting

# Clippy with warnings as errors
cargo clippy --all-targets --all-features -- -D warnings

# Or via Nix (same as CI)
nix build .#clippy -L

Code Guidelines

  • No unsafe code (enforced via #![deny(unsafe_code)] workspace-wide)
  • Use thiserror for error types
  • Use tokio for async runtime
  • Prefer log macros for logging

Pull Requests

  1. Fork and create a feature branch
  2. Make your changes
  3. Ensure all checks pass: 
    nix fmt          # Format code
cargo clippy --all-targets --all-features -- -D warnings
cargo nextest run --workspace
  4. Write meaningful commit messages explaining why, not just what
  5. Open a PR against master

CI

PRs are tested by buildbot-nix which runs:

  • nix flake check (clippy, tests, NixOS VM tests)

CodeRabbit

CodeRabbit provides AI-powered code reviews on PRs. It automatically comments with suggestions for improvements, potential bugs, and style issues.

Codecov

Codecov tracks test coverage. Coverage reports are uploaded automatically after successful builds. PRs show coverage changes inline.

Bencher

Bencher tracks benchmark performance over time. Benchmarks run automatically when buildbot reports a successful build. Results are uploaded to detect performance regressions.

All checks must pass before merging.

NixOS Module Development

The NixOS module is in module.nix. To test changes:

# Test with nix-daemon backend
nix build .#checks.x86_64-linux.nix-daemon -L

# Test with harmonia-daemon backend
nix build .#checks.x86_64-linux.harmonia-daemon -L

Questions?

Open an issue at https://github.com/nix-community/harmonia/issues