Update CONTRIBUTING.md

CONTRIBUTING.md

@@ -144,59 +144,58 @@ Advanced users can pass CMake flags to customize the build.
 
 VSCode is the recommended IDE for working on Bun, as it has been configured. Once opening, you can run `Extensions: Show Recommended Extensions` to install the recommended extensions for Zig and C++. ZLS is automatically configured.
 
-If you use a different editor, make sure that you tell ZLS to use the automatically installed Zig compiler, which is located at `./.cache/zig/zig` (`zig.exe` on Windows).
+If you use a different editor, make sure that you tell ZLS to use the automatically installed Zig compiler, which is located at `./.cache/zig/zig.exe`. The filename is `zig.exe` so that it works as expected on Windows, but it still works on macOS/Linux (it just has a surprising file extension).
 
-## Code generation scripts
+We recommend adding `./build` to your `$PATH` so that you can run `bun-debug` in your terminal:
 
-{% callout %}
+```sh
+$ bun-debug
+```
 
-**Note**: This section is outdated. The code generators are run automatically by ninja, instead of by `make`.
+## Code generation scripts
 
-{% /callout %}
+Several code generation scripts are used during Bun's build process. These are run automatically when changes are made to certain files.
 
-Bun leverages a lot of code generation scripts.
+In particular, these are:
 
-The [./src/bun.js/bindings/headers.h](https://github.com/oven-sh/bun/blob/main/src/bun.js/bindings/headers.h) file has bindings to & from Zig <> C++ code. This file is generated by running the following:
+- `./src/codegen/generate-jssink.ts` -- Generates `build/codegen/JSSink.cpp`, `build/codegen/JSSink.h` which implement various classes for interfacing with `ReadableStream`. This is internally how `FileSink`, `ArrayBufferSink`, `"type": "direct"` streams and other code related to streams works.
+- `./src/codegen/generate-classes.ts` -- Generates `build/codegen/ZigGeneratedClasses*`, which generates Zig & C++ bindings for JavaScriptCore classes implemented in Zig. In `**/*.classes.ts` files, we define the interfaces for various classes, methods, prototypes, getters/setters etc which the code generator reads to generate boilerplate code implementing the JavaScript objects in C++ and wiring them up to Zig
+- `./src/codegen/bundle-modules.ts` -- Bundles built-in modules like `node:fs`, `bun:ffi` into files we can include in the final binary. In development, these can be reloaded without rebuilding Zig (you still need to run `bun run build`, but it re-reads the transpiled files from disk afterwards). In release builds, these are embedded into the binary.
+- `./src/codegen/bundle-functions.ts` -- Bundles globally-accessible functions implemented in JavaScript/TypeScript like `ReadableStream`, `WritableStream`, and a handful more. These are used similarly to the builtin modules, but the output more closely aligns with what WebKit/Safari does for Safari's built-in functions so that we can copy-paste the implementations from WebKit as a starting point.
 
-```bash
-$ make headers
-```
+## Modifying ESM modules
 
-This ensures that the types for Zig and the types for C++ match up correctly, by using comptime reflection over functions exported/imported.
+Certain modules like `node:fs`, `node:stream`, `bun:sqlite`, and `ws` are implemented in JavaScript. These live in `src/js/{node,bun,thirdparty}` files and are pre-bundled using Bun.
 
-TypeScript files that end with `*.classes.ts` are another code generation script. They generate C++ boilerplate for classes implemented in Zig. The generated code lives in:
+## Release build
 
-- [src/bun.js/bindings/ZigGeneratedClasses.cpp](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.cpp)
-- [src/bun.js/bindings/ZigGeneratedClasses.h](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.h)
-- [src/bun.js/bindings/generated_classes.zig](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/generated_classes.zig)
-  To generate the code, run:
+To compile a release build of Bun, run:
 
 ```bash
-$ make codegen
+$ bun run build:release
 ```
 
-Lastly, we also have a [code generation script](src/bun.js/scripts/generate-jssink.js) for our native stream implementations.
-To run that, run:
-
-```bash
-$ make generate-sink
-```
+The binary will be located at `./build-release/bun` and `./build-release/bun-profile`.
 
-You probably won't need to run that one much.
+### Download release build from pull requests
 
-## Modifying ESM modules
+To save you time spent building a release build locally, we provide a way to run release builds from pull requests. This is useful for testing changes before they are merged.
 
-Certain modules like `node:fs`, `node:stream`, `bun:sqlite`, and `ws` are implemented in JavaScript. These live in `src/js/{node,bun,thirdparty}` files and are pre-bundled using Bun. In debug builds, Bun automatically loads these from the filesystem, wherever it was compiled, so no need to re-run `make dev`.
+To run a release build from a pull request, you can use the `bun-pr` npm package:
 
-## Release build
+```sh
+bunx bun-pr pr-number
+bunx bun-pr branch/branch-name
+bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
+```
 
-To build a release build of Bun, run:
+This will download the release build from the pull request and add it to `$PATH` as `bun-${pr-number}`. You can then run the build with `bun-${pr-number}`.
 
-```bash
-$ bun run build:release
+```sh
+bun-1234566 --version
 ```
 
-The binary will be located at `./build-release/bun` and `./build-release/bun-profile`.
+This works by downloading the release build from the GitHub Actions artifacts on the linked pull request. You may need the `gh` CLI installed to authenticate with GitHub.
 
 ## Valgrind