iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article

✍️

A Guide to Submitting Your First Patch to V8

2025/10/06に公開

Introduction

I recently submitted a patch to V8 for the first time, but since it was quite difficult to do so using only the official documentation, I've put this together as a personal memorandum.

I summarized the steps based on these official documents:

https://v8.dev/docs/source-code

Prerequisites for V8 Development

V8 is not on GitHub

What is on GitHub is just a mirror, and you cannot send Pull Requests there. You submit patches to the Chromium repository built with a system called Gerrit. You will also need to create a Gerrit account.

A Google Account is mandatory

You must have a Google account with an email address that matches the one used for commit.

For details on how to use the various related sites used in V8/Chromium development (Code Search, Gitiles, crbug, etc.), this article by jxck is extremely helpful.
Peripheral knowledge for contributing to Chromium

Step 1: Preparation - Getting the code locally

1. Git environment configuration

# Disable automatic conversion of line endings
git config --global core.autocrlf false

# Ignore file permission changes
git config --global core.filemode false

2. Installing depot_tools

A set of tools called depot_tools is mandatory for Chromium/V8 development. First, git clone this and add it to your PATH.

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
export PATH="$(pwd)/depot_tools:$PATH" # Please set this according to your environment

The official documentation is here:

3. Getting the source code

Use the fetch command to acquire the complete V8 source code. Since it is a massive repository, it takes a significant amount of time.

fetch v8

A v8 directory will be created directly under the directory where you executed the command, so move into it.

cd v8

Add the necessary configuration for depot_tools to work with Gerrit.

git config --local gerrit.host true

After acquiring the source code, you will intentionally be in a detached head state.

Step 2: Development and First Commit

1. Updating dependencies and creating a branch

Before starting development, first update the local source code and dependencies.

git pull origin main
gclient sync

Once finished, create a branch for your work. Using git checkout -b is fine, but the official documentation recommends using git new-branch.

git new-branch fix/my-cool-fix

2. Modifying code and adding to the AUTHORS file

Once you have created a branch, modify the code. At the same time, if this is your first contribution, you must add your name and email address to the AUTHORS file in the root directory. This is required by the presubmit check, so it must be included in your first commit. You are expected to add it in alphabetical order, so please add your name and email address to the appropriate place.

First-time contributors
Add your (or your organization's) name and contact info to the AUTHORS file for Chromium or Chromium OS. Please include this as part of your first patch and not as a separate standalone patch.

3. Committing

Before committing, run git cl format to format the code according to the Chromium coding style.

git cl format

Commit the code changes and the AUTHORS file changes together.

git add .
git commit

Commit messages must be written according to V8's conventions. Basically, follow the format [component]: Short description. If there is a related issue, add the Bug: footer, and if manual testing is required, add the Test: footer.

[component] Fix various typos in comments

This patch fixes several spelling mistakes in comments across the codebase.

Bug: v8:12345 # (The v8: part might be another project ID like chromium:)
Fixed: v8:12346 # Using Fixed: will automatically close the issue upon merging

Step 3: Authentication and Presubmit (The challenging part starts here)

1. Creating a Gerrit account

This is where it gets tricky. First, access Gerrit, log in with the Google account you use for commits, and create an account. (I overlooked this and struggled without being able to authenticate for a while 😅)

If you miss this step, you will inevitably run into trouble during the authentication process later, so it is crucial.

2. Signing the CLA

If this is your first time contributing to Google's open-source projects, you must sign the CLA (Contributor License Agreement).

https://cla.developers.google.com/

3. Authentication process

Next, go through the authentication process.

# 0. (First time only) Check/set if Git global settings are correctly configured for Gerrit
git cl creds-check --global

# 1. First, log in to your Google account in your browser to create credentials
#    (Two-factor authentication for your Google account will be required here)
git credential-luci login

# 2. Verify that authentication was successful and Git settings are correct
git cl creds-check

4. Executing Presubmit

Once everything is ready, run the presubmit check. If this passes, you are ready to upload.

git cl presubmit

Step 4: Upload

1. Finding a reviewer

Check the OWNERS file in the directory related to your changes to find an appropriate reviewer.

2. Uploading

Once you have found a reviewer, upload using the -r option followed by their email address.

git cl upload -r [Specify code owner's email address]

You can also run git cl upload without the -r option and add the reviewer later via the Gerrit Web UI. I recommend using the Web UI, as it makes it easier to assign reviewers.

When you run upload, Vim will launch to edit the commit message. Review the contents, and if there are no issues, save and exit with :wq.

Once a URL is generated, the upload is complete.

You can see the actual patch here:

Step 5: Post-upload flow and useful commands

1. Handling reviews and the Commit Queue (CQ)

Once the upload is complete, the reviewer will leave comments on Gerrit. You will repeat the cycle of addressing the review feedback and uploading a new patch set with git cl upload.

You complete the patch by repeating this process. For more details on the review exchange, jxck's article mentioned above is very helpful.

2. Useful commands

These commands are helpful during the development and review cycle:

git cl format: Automatically formats the source code according to the Chromium coding style.
git cl owners: Suggests reviewers from the OWNERS file based on your changes.
git cl issue: After uploading, you can re-check the URL of the review page linked to your current branch in the terminal.

Conclusion

That covers the steps for sending your first patch to V8.
For more detailed information, please refer to the official documentation.