How to contribute

This section is a working guide for people who want to land changes in the Bun repo. The end-user docs at bun.com/docs are managed elsewhere.

TL;DR

1. Branch name must start with claude/ for the CI to pick it up. (Yes, even if you're a human. The CI is gated.)
2. Always test with the debug build. bun bd test <file>. Never bun test directly — it uses the system Bun and skips your changes.
3. Verify the test fails on main and passes on your branch. Run with USE_SYSTEM_BUN=1 bun test <file> (must fail) and then bun bd test <file> (must pass).
4. Be honest about what works. No "fixed and tested" claims unless tests are green.
5. Use bun.*, never std.*. bun.sys, bun.path, bun.strings, bun.spawn, etc. See Patterns and conventions.

The detailed pages:

• Development workflow — branching, PRs, reviews, CI.
• Testing — how the test suite is laid out and what good tests look like.
• Debugging — debug logs, sourcemaps, the inspector, common failures.
• Patterns and conventions — Zig style, bun.* API, JSC bindings, JS builtins.
• Tooling — the build, codegen, lint, format, CI helpers.

Where the project conventions live

The repo has multiple CLAUDE.md / AGENTS.md files that act as authoritative style references for that subtree:

File	Scope
CLAUDE.md (repo root)	Build commands, test conventions, repo-wide rules.
src/CLAUDE.md	Zig conventions, bun.* API surface, syscall patterns.
src/js/CLAUDE.md	JS/TS builtin module syntax ($ prefix, intrinsics).
test/CLAUDE.md	Test layout, harness usage, tempDir etc.
.github/workflows/CLAUDE.md	CI workflow conventions.
.claude/	Per-task playbooks (out of scope for this wiki).

Read the relevant CLAUDE.md before writing in that subtree.

Code review self-check

The repo asks contributors to:

• Pre-emptively answer "why this and not the alternative?" before writing non-obvious code.
• Verify that suggested fixes are at the right layer — don't take a bug report's suggested fix at face value.
• Find out why neighbouring code does something differently before deviating. Existing choices are often load-bearing.

These are quoted from CLAUDE.md's "Code Review Self-Check" section.

Where to ask for help

• The Discord (link in bun discord or the repo README).
• GitHub issues — for reproducible bugs only.
• For specific subsystem questions, see Maintainers for the recent contributor list per area.