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

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.

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 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—structure your test like this:

#[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 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:

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:

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	Official workflow instructions: send git format-patch output to ry@deno.com
crates/logic/ownership.rs	Core ownership logic; frequent target of race-condition fixes
crates/logic/sweep.rs	Lease coordination; source of many reported synchronization bugs
docs/testing.md	Testing strategy guidance for constructing minimal reproductions
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 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 or 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, 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:

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.

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