Merging & Patching

Introduction

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.

For the examples, a branched 2.4 version of V8 will be used. Substitute "2.4" with your version number. See Release Process for more information about version numbers.

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 an issue.

What qualifies a merge candidate?

• The patch fixes a severe bug (order of importance)
  1. Security bug
  2. Stability bug
  3. Correctness bug
  4. Performance bug
• The patch does not alter APIs
• The patch does not change behavior present before branch cut (except if the behavior change fixes a bug)

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

Merge process outlined

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 => This fix should be merged into #.#
2. Merge-Review-{Branch} The merge is not approved yet for #.# e.g. because Canary coverage is missing
3. Merge-Approved-{Branch} => Simply means that the Chrome TPMs have signed off on the merge
4. Merge-Merged-{Branch} => When the merge is done, the Merge-Approved label is swapped with this one. {Branch} is the name/number of the V8 branch e.g. 4.3 for M-43.

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 HASH according to Git.

tools/release/mergeinfo.py 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 it 1.) has approval and 2.) the merge was clean and 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) will take 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 2.4.4.

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

I get an error during merge that is related to tagging. What should I do?

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 issue on 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