# How to Report a Bug in denoland/celld: The Email Patch Workflow Explained

> Learn how to report bugs in denoland/celld using the email patch workflow. This guide explains the git format-patch process for submitting bug reports to ry@deno.com.

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

---

**Send bug reports to the denoland/celld repository as email patches using `git format-patch` mailed to ry@deno.com, since the project disables GitHub pull requests to reduce review overhead.**

The `celld` project is a self-hosted daemon that runs Cloudflare Workers and Durable Objects. When you encounter issues in this distributed systems codebase, you'll need to follow a non-standard contribution workflow. This guide walks through the exact steps to report bugs effectively, based on the project's official policies in [`README.md`](https://github.com/denoland/celld/blob/main/README.md).

## Why denoland/celld Uses Email Patches Instead of Pull Requests

The maintainers explicitly disabled GitHub pull requests to prevent large, low-context changes that increase review burden. According to [`README.md`](https://github.com/denoland/celld/blob/main/README.md) lines 20-22, the **email patch workflow** ensures each contribution is well-understood and focused before integration.

This approach means:

- No "Compare & pull request" button in the GitHub UI
- All fixes arrive as `.patch` files attached to emails
- The maintainer manually applies, verifies, and merges each change

## Step-by-Step: How to Report a Bug in denoland/celld

### 1. Reproduce the Issue Locally

Before reporting, confirm the bug manifests reliably. Run your scenario using `celld dev` or against a real fleet, then capture:

- **Log output** from the failure
- **Seed values** if the bug is deterministic
- **Stack traces** showing where the panic or error occurs

### 2. Create a Minimal Reproducible Example

Isolate the failing code path and add a test that fails before your fix and passes after. For ownership-related bugs—common in [`crates/logic/ownership.rs`](https://github.com/denoland/celld/blob/main/crates/logic/ownership.rs)—structure your test like this:

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

    #[test]
    fn bug_example() {
        // Setup a minimal celld node with an in-memory bucket
        let mut node = TestNode::new();

        // Trigger the failing scenario (e.g., a lease race)
        node.simulate_crash_during_ownership();

        // Assert the expected outcome
        assert!(node.no_acknowledged_write_lost());
    }
}

```

Reference the invariants in [`docs/guarantees.md`](https://github.com/denoland/celld/blob/main/docs/guarantees.md) when defining your test assertions. This helps maintainers understand which system property was violated.

### 3. Generate the Patch with git format-patch

After committing your fix, create the patch file:

```bash
git add crates/logic/ownership.rs
git commit -m "Fix race that could lose an acknowledged write"
git format-patch -1 HEAD   # creates 0001-fix-race.patch

```

**Key flags explained:**

- `-1 HEAD` — Generate patch for exactly one commit (the most recent)
- Output is a `.patch` file containing the diff plus full commit message

### 4. Email the Patch to the Maintainer

Send the patch as an attachment to **ry@deno.com**:

```bash
mail -s "celld bug fix: race on ownership handoff" \
     -a 0001-fix-race.patch \
     ry@deno.com < /dev/null

```

Include a clear subject line describing the bug category and component.

### 5. Reference the GitHub Issue Tracker

Even though pull requests are disabled, the project uses issues for discussion. Link to:

- An existing open issue at <https://github.com/denoland/celld/issues>, or
- Create a new issue describing the bug before sending your patch

This creates a paper trail for the community and helps the maintainer cross-reference your fix with reported symptoms.

## Key Files for Bug Reporters

Understanding these source files accelerates effective bug reporting:

| File | Relevance to Bug Reporting |
|------|---------------------------|
| [`README.md`](https://github.com/denoland/celld/blob/main/README.md) | Official workflow instructions: send `git format-patch` output to `ry@deno.com` |
| [`crates/logic/ownership.rs`](https://github.com/denoland/celld/blob/main/crates/logic/ownership.rs) | Core ownership logic; frequent target of race-condition fixes |
| [`crates/logic/sweep.rs`](https://github.com/denoland/celld/blob/main/crates/logic/sweep.rs) | Lease coordination; source of many reported synchronization bugs |
| [`docs/testing.md`](https://github.com/denoland/celld/blob/main/docs/testing.md) | Testing strategy guidance for constructing minimal reproductions |
| [`docs/guarantees.md`](https://github.com/denoland/celld/blob/main/docs/guarantees.md) | System invariants your test should validate (e.g., no acknowledged write lost) |

## Summary

- **denoland/celld disables GitHub pull requests** by design to control review quality
- **Bug reports take the form of email patches** generated via `git format-patch -1 HEAD`
- **Send patches to ry@deno.com** with descriptive subject lines
- **Always include a failing test** that demonstrates the bug and verifies the fix
- **Reference [`docs/guarantees.md`](https://github.com/denoland/celld/blob/main/docs/guarantees.md)** to anchor your test in system invariants
- **Link to GitHub issues** for community visibility and maintainer context

## Frequently Asked Questions

### What if I can't reproduce the bug consistently?

Intermittent failures in `celld` often indicate race conditions in [`crates/logic/sweep.rs`](https://github.com/denoland/celld/blob/main/crates/logic/sweep.rs) or [`crates/logic/ownership.rs`](https://github.com/denoland/celld/blob/main/crates/logic/ownership.rs). Use `celld dev` with logging enabled, capture the seed value when the failure occurs, and include that seed in your test setup. The maintainer can then run your test with `cargo test --release` using your provided seed.

### Can I report a bug without providing a fix?

Yes. Open an issue at <https://github.com/denoland/celld/issues> with your reproduction steps, logs, and any relevant seeds. The maintainer may request you convert your report to a patch later, or they may implement the fix directly and credit you in the commit.

### Why does celld reject GitHub pull requests specifically?

The project prioritizes **review bandwidth over contribution convenience**. As documented in [`README.md`](https://github.com/denoland/celld/blob/main/README.md), large, undiscussed changes create excessive overhead for a small maintainer team. Email patches force contributors to isolate changes and write clear commit messages before submission, improving review efficiency.

### How do I handle multi-commit fixes?

For changes that require multiple logical commits, generate patches for the commit range:

```bash
git format-patch -3 HEAD   # Last 3 commits

```

This produces numbered patch files (0001-*, 0002-*, 0003-*). Attach all files to a single email with a cover letter explaining the sequence, or send as separate threaded emails if the changes are independent.