Merging & patching

If you have a patch to the master branch (e.g. an important bug fix) that needs to be merged into one of the production V8 branches, read on.

The following examples use a branched 2.4 version of V8. Substitute 2.4 with your version number. Read the documentation on V8’s release process and V8’s version numbering for more information.

An associated issue on Chromium’s or V8’s issue tracker is mandatory if a patch is merged. This helps with keeping track of merges. You can use a template to create a merge request issue.

What qualifies a merge candidate?

More information can be found on the relevant Chromium page. When in doubt, send an email to v8-dev@googlegroups.com.

The merge process

The merge process in the Chromium and V8 tracker is driven by labels in the form of:

Merge-[Status]-[Branch]

The currently important labels for V8 are:

  1. Merge-Request-{Branch} initiates the process, and means that this fix should be merged into {Branch}. {Branch} is the name/number of the V8 branch e.g. 7.2 for M72.
  2. Merge-Review-{Branch} means the merge is not approved yet for {Branch} e.g. because Canary coverage is missing.
  3. Merge-Approved-{Branch} means that the Chrome TPMs have signed off on the merge.
  4. When the merge is done, the Merge-Approved-{Branch} label is replaced with Merge-Merged-{Branch}.

Instructions for Git using the automated script

How to check if a commit was already merged/reverted/has Canary coverage

Use mergeinfo.py to get all the commits which are connected to the $COMMIT_HASH according to Git.

tools/release/mergeinfo.py $COMMIT_HASH

If it tells you Is on Canary: No Canary coverage you should not merge yet because the fix was not yet deployed on a Canary build. A good rule of the thumb is to wait at least 3 days after the fix has landed until the merge is conducted.

Step 1: Run the script

Let’s assume you’re merging revision af3cf11 to branch 2.4 (please specify full git hashes - abbreviations are used here for simplicity).

tools/release/merge_to_branch.py --branch 2.4 af3cf11

Run the script with -h to display its help message, which includes more options (e.g. you can specify a file containing your patch, or you can reverse a patch, specify a custom commit message, or resume a merging process you’ve canceled before). Note that the script will use a temporary checkout of V8 - it won’t touch your work space. You can also merge more than one revision at once; just list them all.

tools/release/merge_to_branch.py --branch 2.4 af3cf11 cf33f1b sf3cf09

In case you are a V8 committer, feel free to use TBR to land the merge if 1) it has approval and 2) the merge was clean and there are no conflicts to resolve.

Step 2: Observe the branch waterfall

If one of the builders is not green after handling your patch, revert the merge immediately. A bot (AutoTagBot) takes care of the correct versioning after a 10-minute wait.

Patching a version used on Canary/Dev

In case you need to patch a Canary/Dev version (which should not happen often), follow these instructions:

Step 1: Merge to roll branch

Example version used is 5.7.433.

tools/release/roll_merge.py --branch 5.7.433 af3cf11

Step 2: Make Chromium aware of the fix

Example Chromium branch used is 2978:

git checkout chromium/2978
git merge 5.7.433.1
git push

Step 3: The end

Chrome/Chromium should should pick of the change when they build automatically.

FAQ

When two people are merging at the same time a race condition can happen in the merge scripts. If this is the case, contact machenbach@chromium.org and hablich@chromium.org.

Is there a TL;DR?

  1. Create an issue on the issue tracker.
  2. Check status of the fix with tools/release/mergeinfo.py
  3. Add Merge-Request-{Branch} to the issue.
  4. Wait until somebody adds Merge-Approved-{Branch}.
  5. Merge.