What agents should know before contributing

oven-sh/bun

Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one

Read by Bluet from 3 files written for agents and 300 merged pull requests on 2026-09-24. Not reviewed by the maintainers.

Rules its files tell agents (11)

mustNever use bun test or bun <file> directly - always use bun bd test or bun bd <command>.
Never use bun test or bun <file> directly - always use bun bd test or bun bd <command>. bun bd compiles & runs the debug build.
CLAUDE.md
mustNever contact the public internet (registry.npmjs.org, github.com, CDNs).
Never contact the public internet (registry.npmjs.org, github.com, CDNs). Use VerdaccioRegistry from "harness" for package installs and a local Bun.serve({ port: 0 }) for HTTP.
CLAUDE.md
mustNEVER write tests that check for no "panic" or "uncaught exception" or similar in the test output.
NEVER write tests that check for no "panic" or "uncaught exception" or similar in the test output. These tests will never fail in CI.
CLAUDE.md
mustThe types test just packs the .d.ts files and runs tsc against fixtures — it never executes your build.
Edits to TypeScript type declarations (packages/bun-types/**/*.d.ts) do not touch any compiled code, so bun bd is unnecessary. The types test just packs the .d.ts files and runs tsc against fixtures — it never executes your build. Run it directly with the system Bun (an explicit exception to the "never use bun test directly" rule):
CLAUDE.md
mustCRITICAL: Never use bun test directly - it won't include your changes
CLAUDE.md
should⚠️ Ubuntu distributions (<= 20.04) may require installation of the C++ standard library independently.
⚠️ Ubuntu distributions (<= 20.04) may require installation of the C++ standard library independently. See the troubleshooting section for more information.
CONTRIBUTING.md
shouldDo not use tmpdirSync or fs.mkdtempSync to create temporary directories.
Use tempDir from "harness" to create a temporary directory. Do not use tmpdirSync or fs.mkdtempSync to create temporary directories.
CLAUDE.md
shouldCRITICAL: Do not write flaky tests.
CRITICAL: Do not write flaky tests. Do not use setTimeout or await sleep(N) to wait for a condition; poll with a deadline or await the event itself. You are not testing the TIME PASSING, you are testing the CONDITION.
CLAUDE.md
shouldDo not hardcode ports.
Always use port: 0. Do not hardcode ports. Do not use your own random port number function.
CLAUDE.md
shouldDo not create a new file.
Default: add your test to the existing test file for the code you're changing. Do not create a new file. A fetch bug goes in test/js/web/fetch/fetch.test.ts, a Bun.serve bug goes in test/js/bun/http/serve.test.ts, and so on. Keeping tests next to related coverage is what makes them discoverable and prevents duplicated setup.
CLAUDE.md
shouldCRITICAL: do not set a timeout when running bun bd
CLAUDE.md

Decisions its pull requests settled (40)

#41771fetch: never send the URL fragment in the request-target
#41757Direct streams read from JS: own the buffer, signal backpressure, run cancel()
#41828minify: do not fold new Array(x, ...spread) into an array literal
#41894Bun.serve direct streams: flush on controller.close(), end the response once, call cancel() only on a client abort
#41891fetch: close connections evicted from a full keep-alive pool with FIN, not RST
#41987fetch: do not reuse a pooled connection the origin already wrote to
#42038FileReader: release the event loop while a pipe reader is stopped at its highwater mark
#42024fetch: decide a streaming request body's framing once, reject caller framing headers it cannot honor
#42053webcore: clone() keeps the Blob behind an unread native body stream instead of teeing it
#42110bun test --isolate: drop a retired file's deferred work
#42114Native sinks root only their controller cell; fix a leaked flush(true) promise when end() hits backpressure
#42125Error the original body's stream after clone() when the body fails, instead of ending it
#42130HTMLRewriter: cancel a still-open JS stream input when the rewrite fails or its output is cancelled
#42128node:http: destroy an idle pooled keep-alive socket that receives unsolicited data
#42150terminal: release the wrapper after PTY EOF leaves input unflushed
#42176node:tls: keep unread data and still emit 'close' when a wrapped transport closes
#42161secrets: add a persist option for Windows Credential Manager entries
#42202Throw instead of aborting when an ERR_* error message passes the string length limit
#42208node:crypto: make Hash update()/copy() after end() throw instead of reusing the finalized context
#42213node:net: honor readable/writable in the Socket constructor so a write-only adopted fd stays open
#42245Fix the segfault in TOML.stringify on a deeply nested table
#42219bun:sqlite: bind a detached TypedArray as an empty BLOB, reject 2 GiB values instead of truncating
#42288shell: reject the promise and stop the pipeline when a member throws a JS error
#42287mock.module: patch an already-loaded module when a pending factory promise settles, instead of spinning
#42314Drop the frames instead of aborting when a stack trace passes the string length limit
#42521perf_hooks: fix crash when a PerformanceObserver callback comes from a node:vm context
#42346Keep require() and import() locals working in functions the React Compiler compiles
#42642react-compiler: hoist the declaration of a local that a later scope assigns
#42644react-compiler: keep a store or update in place when its value folds
#42649streams: throw instead of aborting when a script-sized container cannot grow
#42690Bun.serve(http3): keep accepting the client's unidirectional streams after GOAWAY
#42661http: verify a proxied origin with the HTTP thread's CA configuration
#42689node-fetch: reject json() on an empty body
#42692fetch: proxy, TLS identity and error fixes; add Bun.FetchSession
#42732quic: drop a datagram the kernel refuses to send instead of pausing the HTTP/3 engine
#42731Release the consumed prefix of StreamBuffer so S3 uploads do not keep the whole payload in memory
#42765http(h3): abort a request with RESET_STREAM, not FIN
#42796Bun.serve: send the completed responses of a pipelined read before JavaScript runs again
#42798UTF8View: throw instead of aborting when a string does not convert to UTF-8
#42823Upgrade WebKit to d3720d515e14: module linking without sorting import names or resolving every import up front

Your agents can be told this before they touch the code. Get it for your repository: npx bluet-mcp init. What Bluet is.