Contributing Guide

How to contribute to RISC Zero and help improve the zkVM

Welcome Contributors

Thank you for your interest in contributing to RISC Zero! We welcome contributions from everyone, whether you’re fixing a typo, adding documentation, or implementing new features.

If you have questions about contributing or the project in general, please ask in our Discord channel.

Quick Start

To set up your development environment and run the test suite, you’ll need several dependencies.

Prerequisites

Git Large File Storage

Install Git LFS and initialize it:

git lfs install
git lfs pull

Rust

Install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

RISC Zero Toolchain

Install the RISC Zero toolchain with rzup:

cargo run --bin rzup install rust
cargo run --bin rzup install cpp

For development branches, the versions of r0vm and cargo-risczero must match the source code. Compile and install from source:

cargo install --force --path risc0/cargo-risczero

For Stable Versions

If using a stable version branch, install via the standard flow:

curl -L https://risczero.com/install | bash
rzup install

Optional: WASM Tools

If testing the browser-verify example:

cargo xtask install
cargo xtask gen-receipt

Development Workflow

Fork and Branch

1. Fork the repository on GitHub
2. Clone your fork:
   git clone https://github.com/YOUR_USERNAME/risc0.git
   cd risc0
   
3. Create a feature branch:
   git checkout -b feature/your-feature-name
   

Always create a new branch for your work. Do not commit directly to main.

Making Changes

1. Write your code following the project’s style and conventions
2. Add tests for new functionality
3. Update documentation as needed
4. Run the PR checklist (see below) before submitting

PR Checklist

Before submitting a pull request, ensure the following:

1. Format Code

Run cargo fmt on all code:

cargo fmt --all

2. Run Linter

Run clippy to catch common mistakes:

RISC0_SKIP_BUILD=1 cargo clippy
(cd examples && RISC0_SKIP_BUILD=1 cargo clippy)

RISC0_SKIP_BUILD=1 speeds up linting by skipping guest builds.

3. License Check

Run the license check script:

python3 license-check.py

This ensures all files have proper license headers.

4. Run Tests

Run the full test suite:

cargo test -F prove -F docker
(cd examples && cargo test)

Tests with proving enabled can take significant time and resources. Consider running without -F prove for quick iteration, then run full tests before submitting.

5. Update Cargo.lock

If dependencies changed, commit the updated Cargo.lock:

git add Cargo.lock
git commit -m "Update Cargo.lock"

6. Open Pull Request

Open a PR against the main branch with:

• Clear description of changes
• Reference to related issues (if applicable)
• Screenshots or examples (if relevant)

Contribution Areas

Code Contributions

Bug Fixes

Fix reported issues and improve stability

Features

Implement new functionality

Performance

Optimize execution or proving performance

Examples

Add new example applications

Documentation Contributions

• Fix typos and improve clarity
• Add missing documentation
• Create tutorials and guides
• Update outdated information

Documentation contributions are just as valuable as code contributions!

Testing Contributions

• Add test coverage for untested code
• Create regression tests for fixed bugs
• Improve test infrastructure
• Add benchmarks

Coding Standards

Rust Style

• Follow standard Rust conventions
• Use cargo fmt for formatting
• Address clippy warnings
• Write idiomatic Rust code

Commit Messages

Write clear, descriptive commit messages:

Short summary (50 chars or less)

Detailed explanation of what changed and why.
Reference issues with #123 syntax.

Documentation

• Add doc comments for public APIs:

  /// Brief description
  ///
  /// # Arguments
  /// * `arg` - Description
  ///
  /// # Examples
  /// ```
  /// // Example usage
  /// ```
  pub fn function(arg: Type) { }
  

• Update README.md files when adding features

• Keep documentation in sync with code changes

Testing Guidelines

Unit Tests

Add unit tests for new functionality:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // Test implementation
    }
}

Integration Tests

Add integration tests in the tests/ directory for complex functionality.

Running Specific Tests

# Run specific test
cargo test test_name

# Run tests in specific module
cargo test module_name

# Run with output
cargo test -- --nocapture

Performance Considerations

Profiling

When optimizing performance:

1. Measure first: Use RISC0_INFO=1 to profile
2. Benchmark: Add benchmarks for critical paths
3. Document: Explain performance improvements in PR

Benchmarking

Add benchmarks to benches/:

use criterion::{criterion_group, criterion_main, Criterion};

fn benchmark_function(c: &mut Criterion) {
    c.bench_function("function_name", |b| b.iter(|| {
        // Code to benchmark
    }));
}

criterion_group!(benches, benchmark_function);
criterion_main!(benches);

Debugging

Common Issues

Build fails after pulling changes

Try a clean rebuild:

cargo clean
cargo build

Test hangs or fails

Run with debug output:

RUST_LOG=debug cargo test test_name -- --nocapture

Clippy errors

Some clippy warnings can be allowed in specific contexts:

#[allow(clippy::lint_name)]

However, prefer fixing the warning when possible.

Getting Help

Community Resources

Discord

Ask questions and discuss with the community

GitHub Discussions

Long-form discussions and Q&A

GitHub Issues

Report bugs and request features

Documentation

Read the comprehensive documentation

Getting Reviews

• Be responsive to review feedback
• Ask questions if feedback is unclear
• Keep PRs focused and reasonably sized
• Be patient - maintainers review in their spare time

Code of Conduct

We expect all contributors to:

• Be respectful and inclusive
• Welcome newcomers
• Accept constructive criticism gracefully
• Focus on what’s best for the community
• Show empathy towards others

By participating in this project, you agree to abide by our community standards.

Recognition

Contributors are recognized in:

• Release notes for significant contributions
• GitHub contributors page
• Community shoutouts on Discord

License

By contributing to RISC Zero, you agree that your contributions will be licensed under the project’s license.

Ensure you have the right to contribute the code and that it doesn’t violate any third-party licenses.

Next Steps

1. Set up your environment

   Install all prerequisites and clone the repository

2. Find an issue

   Look for issues tagged “good first issue” or “help wanted”

3. Make your contribution

   Follow the development workflow and PR checklist

4. Submit your PR

   Open a pull request and respond to feedback

Thank you for contributing to RISC Zero!