# How to Contribute to the denoland/celld Project: A Complete Guide

> Learn how to contribute to the denoland/celld project. Submit patches via email to ry@deno.com following a strict git format patch process for quality control.

- Repository: [Deno/celld](https://github.com/denoland/celld)
- Tags: how-to-guide
- Published: 2026-09-05

---

**Submit patches via email to `ry@deno.com` after generating a clean `git format-patch`, since the project disables GitHub Pull Requests to maintain strict quality control.**

The **denoland/celld** project implements a self-hosted daemon that runs **Cloudflare Workers** and **Durable Objects** on your own infrastructure. Understanding how to contribute to this repository requires familiarity with its email-based workflow, three-layer architecture, and the specific areas where focused improvements are welcomed.

## How the celld Architecture Shapes Contributions

The codebase is organized into three distinct layers. Knowing which layer your change targets helps you locate the right files and follow existing patterns.

| Layer | Purpose | Key Files |
|:---|:---|:---|
| **Node & Fleet** | Process-level orchestration—each `node` runs a V8 instance, loads Wrangler bundles, and coordinates with peers via a shared bucket | [`crates/celld/main.rs`](https://github.com/denoland/celld/blob/main/crates/celld/main.rs) (actor setup, HTTP listeners) |
| **Logic Core** | Routing, leasing, replication, and durability guarantees | [`crates/logic/lib.rs`](https://github.com/denoland/celld/blob/main/crates/logic/lib.rs) (`celld_logic::routing::Dispatcher`) |
| **Storage & Replication** | SQLite writes captured as **LTX log entries**, replicated via bucket abstraction | [`crates/ltx/src/replica.rs`](https://github.com/denoland/celld/blob/main/crates/ltx/src/replica.rs), [`crates/celld/storage.rs`](https://github.com/denoland/celld/blob/main/crates/celld/storage.rs) |

When contributing to **celld**, start by identifying which layer your change affects. Bug fixes in request routing belong in `crates/logic`, while improvements to cross-node replication target `crates/ltx`.

## Step-by-Step Contribution Workflow

### 1. Review the Contribution Policy

The README at `README.md#contributions` contains the definitive policy. Key points:

- **Pull requests are disabled** on the GitHub repository
- All contributions must arrive as email-attached patches
- The license grant is implicit upon sending your patch

### 2. Build and Run Locally

Clone the repository and verify your development environment:

```bash
git clone https://github.com/denoland/celld.git
cd celld
cargo build

```

Start a local development node:

```bash
celld dev

```

This creates a single-node instance storing data in `.celld/dev` and loads the example Worker from [`examples/wsecho/index.js`](https://github.com/denoland/celld/blob/main/examples/wsecho/index.js). Use this mode to test logic or storage changes without configuring cloud storage.

### 3. Select a Focused Improvement Area

Contributions to **denoland/celld** should be single-purpose and well-scoped. Recommended entry points:

- **`crates/logic`** — routing fixes, scheduler improvements, cell lifecycle edge cases
- **`crates/ltx`** — LTX compression, replication protocol enhancements
- **`crates/celld`** — CLI commands, configuration handling, observability
- **`docs/`** — accuracy fixes, missing guarantee explanations, operational guides

Avoid mixing unrelated changes. A patch that fixes a race condition in `dispatch_do_call` *and* renames variables for style will be rejected.

### 4. Create and Test Your Change

Follow the quality checklist before generating your patch:

| Requirement | Verification |
|:---|:---|
| Clean build | `cargo build` succeeds |
| Tests pass | `cargo test` exits clean |
| New behavior tested | Unit or integration test added in same crate |
| Documentation updated | `docs/*.md` or [`README.md`](https://github.com/denoland/celld/blob/main/README.md) reflects changes |
| Single logical change | No unrelated refactoring included |

### 5. Generate and Email the Patch

Create a formatted patch from your commit:

```bash
git format-patch -1 HEAD

```

Email the resulting `.patch` file to `ry@deno.com` with:

- Clear subject line describing the change
- Brief motivation paragraph
- Reference to affected source lines (e.g., "Fix race in `dispatch_do_call` at line 8000 of [`main.rs`](https://github.com/denoland/celld/blob/main/main.rs)")

The maintainers apply patches with `git am`, so preserving your commit message and authorship metadata matters.

## Essential CLI Commands for Contributors

These invocations help you exercise the systems you may extend:

```bash

# Deploy a Worker to a bucket (triggers fleet-wide adoption)

celld deploy . --bucket s3://my-cells-bucket

# KV operations (exercises bucket replication logic)

celld kv bulk put sessions wrangler-export.json --bucket s3://my-cells-bucket

# Queue lifecycle management

celld queue pause jobs --bucket s3://my-cells-bucket

# Force generation adoption (tests reload logic in main.rs)

celld reload

```

## Key Source Files to Study

Understanding these files prepares you for effective contributions to **celld**:

| File | Responsibility | Direct Link |
|:---|:---|:---|
| [`crates/celld/main.rs`](https://github.com/denoland/celld/blob/main/crates/celld/main.rs) | Binary entry point; actor, bucket, HTTP server initialization | [source](https://github.com/denoland/celld/blob/main/crates/celld/main.rs) |
| [`crates/logic/lib.rs`](https://github.com/denoland/celld/blob/main/crates/logic/lib.rs) | Core routing, scheduling, cell lifecycle | [source](https://github.com/denoland/celld/blob/main/crates/logic/lib.rs) |
| [`crates/ltx/src/replica.rs`](https://github.com/denoland/celld/blob/main/crates/ltx/src/replica.rs) | LTX log replication and durability | [source](https://github.com/denoland/celld/blob/main/crates/ltx/src/replica.rs) |
| [`crates/celld/storage.rs`](https://github.com/denoland/celld/blob/main/crates/celld/storage.rs) | Bucket abstraction (S3/GCS/Azure), lease handling | [source](https://github.com/denoland/celld/blob/main/crates/celld/storage.rs) |
| [`docs/README.md`](https://github.com/denoland/celld/blob/main/docs/README.md) | Developer documentation, guarantees, limits | [source](https://github.com/denoland/celld/blob/main/docs/README.md) |
| [`examples/wsecho/index.js`](https://github.com/denoland/celld/blob/main/examples/wsecho/index.js) | Minimal Worker for local testing | [source](https://github.com/denoland/celld/blob/main/examples/wsecho/index.js) |

## Summary

- **celld contribution to denoland/celld** requires email-based patches, not GitHub PRs
- The architecture divides into **Node & Fleet**, **Logic Core**, and **Storage & Replication** layers
- Run `celld dev` for local testing without cloud storage configuration
- Generate patches with `git format-patch -1 HEAD` and email to `ry@deno.com`
- Include line-number references and follow the single-purpose change rule
- All patches must build, pass tests, include coverage for new behavior, and update documentation

## Frequently Asked Questions

### Why does celld reject GitHub Pull Requests?

The maintainers prioritize review efficiency over contribution convenience. Email patches allow `git am` application with preserved metadata and filter out high-volume, low-context submissions that consume disproportionate review time. The project's strict quality gates are maintained through this selective intake process.

### What makes a patch likely to be accepted?

Small scope, clear motivation, passing tests, and precise documentation. A patch that adds LTX compression benchmarks in `crates/ltx/tests/` with updated [`docs/README.md`](https://github.com/denoland/celld/blob/main/docs/README.md) references stands better odds than a broad refactor. Referencing exact line numbers in your email (visible in GitHub's source view) demonstrates first-hand code knowledge.

### Can I contribute without setting up cloud storage?

Yes. The `celld dev` command runs a local-only node using `.celld/dev` for state. This suffices for logic, routing, and storage abstraction testing. Cloud bucket configuration is only required for multi-node fleet behavior or deployment testing.

### How do I test changes to the routing dispatcher?

Build with `cargo build`, run `celld dev`, then exercise paths through the [`examples/wsecho/index.js`](https://github.com/denoland/celld/blob/main/examples/wsecho/index.js) Worker. For deeper validation, add unit tests in `crates/logic/tests/` that invoke `celld_logic::routing::Dispatcher` directly, following existing test patterns in that crate.