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

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 (actor setup, HTTP listeners)
Logic Core	Routing, leasing, replication, and durability guarantees	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, 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:

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

Start a local development node:

celld dev

This creates a single-node instance storing data in .celld/dev and loads the example Worker from 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 reflects changes
Single logical change	No unrelated refactoring included

5. Generate and Email the Patch

Create a formatted patch from your commit:

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")

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:

# 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	Binary entry point; actor, bucket, HTTP server initialization	source
crates/logic/lib.rs	Core routing, scheduling, cell lifecycle	source
crates/ltx/src/replica.rs	LTX log replication and durability	source
crates/celld/storage.rs	Bucket abstraction (S3/GCS/Azure), lease handling	source
docs/README.md	Developer documentation, guarantees, limits	source
examples/wsecho/index.js	Minimal Worker for local testing	source

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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}