# V8 Updates

To update the version of V8 used by workerd, the steps are:

1. Check <https://chromiumdash.appspot.com/> and identify the latest version of V8 used by the beta versions of Chrome beta.

2. Install `depot_tools` if it is not already present on your machine.

   <https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up>

3. Fetch a local copy of V8:

   ```sh
   mkdir v8
   cd v8
   fetch v8
   ```

   You should probably put this outside of your workerd repo to avoid confusing Bazel.

4. Sync the local copy of V8 to the version used by workerd.

   First, find workerd's current version of V8 in `build/deps/v8.MODULE.bazel`. We will call this `<old_version>`.

   Then sync your fetched version v8 based on the tag.

   ```sh
   cd <path_to_v8>/v8
   git checkout <old_version>
   gclient sync
   ```

5. Create a V8 branch for workerd's V8 patches in your local copy of V8.

   ```sh
   git checkout -b workerd-patches
   git am <path_to_workerd>/patches/v8/*
   ```

6. Rebase the workerd V8 changes onto the new version of V8. For example, assuming
   we are updating to `<new_version>`, the command would be:

   ```sh
   git rebase --onto <new_version> <old_version>
   ```

   There is usually some minor patch editing required during a rebase.

   Ideally at this stage, you should be able to build and test the local V8 with the
   patches applied. See the V8 [Testing](https://v8.dev/docs/test) page.

7. Re-generate workerd's V8 patches.

   ```sh
   git format-patch --full-index -k --no-signature --no-stat --zero-commit <new_version>
   ```

8. Remove the existing patches from `<path_to_workerd>/patches/v8` and copy over the latest generated patches
from the V8 directory.

9. Update the `VERSION` for V8 in `build/deps/v8.MODULE.bazel`.

    The list of patches should be refreshed if new patches are being added or existing
    patches are being removed.

    `INTEGRITY` needs to be updated to the new value. You can get the new value in
    bazel's preferred format just by looking into the mismatch error while trying to compile
    workerd using the newer V8 version or by running
    `openssl dgst -sha256 -binary <tarball_filename> | openssl base64 -A`
    where `<tarball_filename>` is the file available at
    `https://github.com/v8/v8/archive/refs/tags/<new_version>.tar.gz`

10. Update V8's dependencies in `v8.MODULE.bazel` and `deps.MODULE.bazel`.

    You can find the commit versions for V8's dependencies under `<path_to_v8>/DEPS`.

    These currently include `perfetto`, `com_googlesource_chromium_icu` and `simdutf`.
    Note that V8 depends on `perfetto` and `simdutf` via chromium so you can't trivially
    figure out what version of the github code V8 depends on. Instead, it should be safe
    to just bump these dependencies to the latest version on github.

11. Check workerd's tests pass with the updated V8.

     ```sh
     bazel test //...
     ```

12. Commit your workerd changes and push them for review.