# How to Contribute to the iroh Project: A Complete Developer’s Guide

> Learn how to contribute to the iroh project. Follow this guide to fork, branch, implement changes in Rust crates, and submit a pull request to the n0-computer/iroh repository.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Start with a discussion or issue in the n0-computer/iroh repository, fork and branch from `main`, implement your changes in the appropriate Rust crate, and submit a draft pull request following the guidelines in [`CONTRIBUTING.md`](https://github.com/n0-computer/iroh/blob/main/CONTRIBUTING.md).**

The iroh project is a Rust-based peer-to-peer networking stack built on QUIC, providing hole-punching, relay services, and DNS resolution. Contributing to this open-source repository requires understanding its modular workspace architecture and adhering to the structured workflow defined by the maintainers. Whether you are fixing a bug or adding a new feature, knowing how to navigate the crate structure ensures your contribution lands smoothly.

## Understand the iroh Workspace Architecture

The iroh repository is organized as a Cargo workspace containing multiple specialized crates. Understanding which crate owns specific functionality prevents circular dependencies and ensures code lands in the correct location.

### Core Library and Supporting Crates

- **`iroh`** – The core library located in [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs) that exposes the public API for hole-punching and connection establishment.
- **`iroh-relay`** – Implements the relay client and server logic in [`iroh-relay/src/server.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/server.rs) for public relay nodes.
- **`iroh-base`** – Contains shared types like `EndpointId` and `RelayUrl` in [`iroh-base/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/lib.rs) used across the workspace.
- **`iroh-dns`** and **`iroh-dns-server`** – Provide DNS-based address lookup (Pkarr) for endpoint IDs, with source in [`iroh-dns/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/src/lib.rs).
- **Workspace Configuration** – The top-level [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml) defines all workspace members and build profiles.

## Step-by-Step Contribution Workflow

The project follows a well-defined contribution workflow documented in [`CONTRIBUTING.md`](https://github.com/n0-computer/iroh/blob/main/CONTRIBUTING.md). Adhering to these steps ensures your changes align with project standards and receive timely review.

1. **Discuss**: Open a thread on the [GitHub Discussions](https://github.com/n0-computer/iroh/discussions) page to clarify scope or bounce ideas before writing code.

2. **File an Issue**: Search existing issues for duplicates. If none exist, create a new issue describing the bug or feature, optionally labeling it as `feature` or `bug` using the repository templates.

3. **Fork and Clone**: Fork the repository via the GitHub interface, then clone your fork locally:

   ```bash
   git clone https://github.com/<your-username>/iroh.git
   cd iroh
   ```

4. **Create a Branch**: Use descriptive branch names that indicate the purpose, such as `feat/socket-metrics` or `fix/connection-timeout`:

   ```bash
   git checkout -b feat/socket-metrics
   ```

5. **Implement the Change**: Modify code in the appropriate crate (e.g., [`iroh/src/socket/metrics.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/socket/metrics.rs)). Follow Rust documentation conventions and ensure your changes do not introduce circular dependencies between crates.

6. **Write Tests**: Add unit tests alongside your implementation and integration tests under `iroh/tests/` or the relevant crate's test directory. Run `cargo test` to verify functionality.

7. **Open a Draft Pull Request**: Push your branch and open a PR marked as a *draft* to signal work-in-progress. The PR template requires a description, breaking change notes, and a completion checklist including self-review and documentation updates.

8. **Review and Merge**: Respond to reviewer feedback, iterate on the code, and mark the PR as "Ready for review" once stable. Approved contributions are merged into the main branch.

## Practical Example: Adding Socket Metrics

Consider contributing a feature that tracks active QUIC streams per socket. This example demonstrates where to place code and how to test it within the workspace structure.

### Implementing the Metrics Struct

Add the following to [`iroh/src/socket/metrics.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/socket/metrics.rs) to track socket statistics:

```rust
/// Tracks basic socket statistics.
#[derive(Default, Debug, Clone)]
pub struct SocketMetrics {
    /// Current number of open QUIC streams.
    pub open_streams: usize,
}

impl SocketMetrics {
    /// Increment the open-stream counter.
    pub fn inc_streams(&mut self) {
        self.open_streams += 1;
    }

    /// Decrement the open-stream counter.
    pub fn dec_streams(&mut self) {
        self.open_streams = self.open_streams.saturating_sub(1);
    }
}

```

### Exposing the Public API

In [`iroh/src/socket.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/socket.rs), provide a public accessor method:

```rust
impl Socket {
    /// Return a copy of the current metrics.
    pub fn metrics(&self) -> SocketMetrics {
        self.metrics.clone()
    }
}

```

### Integration Testing

Create [`iroh/tests/socket_metrics.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/tests/socket_metrics.rs) to verify the functionality:

```rust
#[tokio::test]
async fn test_socket_metrics() {
    let endpoint = iroh::Endpoint::bind().await.unwrap();
    let socket = endpoint.socket(); // hypothetical accessor
    let mut metrics = socket.metrics();

    // Simulate opening two streams.
    metrics.inc_streams();
    metrics.inc_streams();
    assert_eq!(metrics.open_streams, 2);

    // Simulate closing one stream.
    metrics.dec_streams();
    assert_eq!(metrics.open_streams, 1);
}

```

Run the test suite with `cargo test` to validate your implementation.

## Essential Files for Contributors

Before contributing, familiarize yourself with these key files in the n0-computer/iroh repository.

### CONTRIBUTING.md

The [`CONTRIBUTING.md`](https://github.com/n0-computer/iroh/blob/main/CONTRIBUTING.md) file at the repository root contains the complete contribution workflow, PR style guide, and review checklist. This is the primary reference for submission standards.

### README.md

[`README.md`](https://github.com/n0-computer/iroh/blob/main/README.md) provides the high-level project description, lists all workspace crates, and outlines licensing information.

### Workspace Configuration

The top-level [`Cargo.toml`](https://github.com/n0-computer/iroh/blob/main/Cargo.toml) lists all workspace members and defines global build profiles. Consult this file to understand crate dependencies and feature flags.

### Core Source Files

- **[`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs)** – The public API surface for the core library.
- **[`iroh-relay/src/server.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/server.rs)** – Core relay server implementation, a common target for performance or security improvements.
- **[`iroh-base/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-base/src/lib.rs)** – Shared types such as `EndpointId` and `RelayUrl`.
- **[`iroh-dns/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-dns/src/lib.rs)** – DNS and Pkarr address-lookup logic for extending name resolution.

## Summary

- The iroh project is a Rust workspace split into specialized crates including `iroh`, `iroh-relay`, `iroh-base`, and `iroh-dns`.
- Always start contributions by discussing changes in GitHub Discussions or filing an issue to avoid duplicate work.
- Follow the 8-step workflow: discuss, issue, fork, branch, implement, test, draft PR, and review.
- Place code in the appropriate crate (e.g., `iroh/src/` for core features, `iroh-relay/src/` for relay logic) to avoid architectural conflicts.
- Reference [`CONTRIBUTING.md`](https://github.com/n0-computer/iroh/blob/main/CONTRIBUTING.md) for the complete style guide and submission checklist.

## Frequently Asked Questions

### Do I need to sign a Contributor License Agreement (CLA) to contribute to iroh?

The source analysis does not mention a CLA requirement. According to the repository guidelines in [`CONTRIBUTING.md`](https://github.com/n0-computer/iroh/blob/main/CONTRIBUTING.md), contributors should follow the standard GitHub fork-and-pull workflow. Review the [`README.md`](https://github.com/n0-computer/iroh/blob/main/README.md) for specific licensing terms, as the project typically requires contributions under the existing open-source license.

### Which crate should I modify to fix a bug in hole-punching logic?

Hole-punching and connection establishment logic resides in the **`iroh`** crate, specifically within [`iroh/src/lib.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/lib.rs) and related socket modules. For changes to how endpoints interact with relay servers, you may also need to modify **`iroh-relay`** in [`iroh-relay/src/server.rs`](https://github.com/n0-computer/iroh/blob/main/iroh-relay/src/server.rs).

### How do I run tests before submitting my contribution?

Execute `cargo test` from the workspace root to run the full test suite. For faster iteration, run tests for a specific crate using `cargo test -p iroh` or target specific integration tests in `iroh/tests/`. Ensure all tests pass and your code follows `rustfmt` standards before marking your PR as ready for review.

### Can I contribute documentation improvements without writing code?

Yes. Documentation contributions follow the same workflow: file an issue describing the gap, fork the repository, and edit the relevant `.md` files or Rust doc comments. Open a draft PR with your changes, ensuring examples compile and links remain valid. The maintainers welcome improvements to both the API documentation and high-level guides.