Skip to content
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .claude/commands/upgrade-webkit.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ To do that:
- Fix the merge conflicts (preserve the fork's Bun-specific changes)
- bun run jsc:build:debug — from the bun repo root, builds just JSC (and its `jsc` shell), in bun's own build graph. File lists come from the checkout, but `scripts/build/deps/webkit.ts` restates WebKit's generator commands, compiler flags and option values by hand, and nothing checks them. Read `git diff $OLD_BASE upstream/main -- Source/cmake Source/JavaScriptCore/CMakeLists.txt Source/WTF/wtf/CMakeLists.txt Source/bmalloc/CMakeLists.txt` for changed `add_custom_command`s (→ `gen()`), compiler flags (→ `webkitFlags()`) and `WEBKIT_OPTION_*` / `SET_AND_EXPOSE_TO_BUILD` (→ `rows`), and carry them over in the bun PR
- While it compiles, in another task review the JSC commits between $OLD_BASE and upstream/main (Source/JavaScriptCore, Source/WTF, Source/bmalloc). Write up a summary in a file called "webkit-changes.md"
- In the same task, run `BUN_WEBKIT_PATH=vendor/WebKit bun scripts/webcore-copies.ts $OLD_BASE upstream/main` from the bun repo root. Put the commit id in place of `$OLD_BASE` if the task's shell does not have the variable. `BUN_WEBKIT_PATH` makes the script read the clone of this routine, also when the shell has another value for it. The script lists the upstream commits in that range that touch a file Bun has its own copy of. Bun does not build Source/WebCore. The files under src/jsc/bindings that come from it (most are in webcore/ and webcrypto/) were copied and edited by hand, and the merge does not change them. An upstream fix reaches a copy only when it is ported. The build is reading the bun checkout: in this task, change no file of the checkout but webkit-changes.md and, where a line below says so, `upstreamOf` in the script
- For each commit, read `git -C vendor/WebKit show <sha> -- <the files listed under it>` beside Bun's copy. A behavior change (a bug fix, a spec update) applies when the copy still has the code that it changes, even where the lines no longer match. If the title names a behavior, try it with the installed `bun`. A refactor that changes no behavior needs no port
- "% same" is how much of the code of the upstream file the copy also has. The upstream file is taken as it was before these commits, or as the commit that adds it has it. A file with fewer than 8 lines of code has no number. The number tells how well a diff of the file lines up with the copy. It is low when Bun has few of the file's functions, and when either side has edited them. A low number is no reason to skip a commit
- "(binding)" marks Bun's `JS<Name>.cpp` for a changed `<Name>.idl`: compare the change with that binding
- "(gone)" marks an upstream file that the new base does not have, on each commit that touches it. `git -C vendor/WebKit show --stat <sha>` of the newest of those commits shows where its code went
- `upstreamOf` in the script names the upstream files of a copy that have another file name than the copy. Without an entry, only a file of the same name leads to a copy. When a commit moves code of a copy into an upstream file of another name (it renames the file or splits it), name that file for the copy in `upstreamOf` and run the script again. When the script says that a file in `upstreamOf` "is gone since" a commit, name the file that has its code now, or take the file out
- Not listed: changes to upstream's implementation of streams. src/jsc/bindings/webcore/streams is Bun's own. A changed `.idl` of a stream class is listed when Bun has a `JS<Name>.cpp` for it. Also not listed: WebCore code that Bun keeps in a file of another name, unless `upstreamOf` names it
- In webkit-changes.md, write how many commits the script listed. For each commit that applies, write the number of the issue or PR that already covers it (search first), of the PR that ports it ("this PR" for a port in the upgrade PR), or of a new issue. Write "already in Bun" for a fix that Bun has in another form. Port with a test, after the build below has finished or in a PR of its own
- bun run build:local — full Bun build with the local WebKit (same build directory and objects as the JSC build above)
- After it compiles, run some code to make sure things work: `bun run build:local -p '42'`
- Publish the new WebKit:
Expand Down
Loading
Loading