Maintaining V8 in Node.js
V8 follows the Chromium release schedule. The support horizon for Chromium is different compared to the support horizon for Node.js. V8 branches in Node.js lack of an official maintenance process due to a missing LTS supported branch.
This document attempts to outline the current maintenance processes, proposes a workflow for maintaining the V8 branches in both Node.js LTS and current releases, and discusses how the Node.js and V8 teams at Google can help.
V8 Release Schedule
V8 and Chromium follow a roughly 6-week release cadence. At any given time there are three V8 branches that are active.
For example, at the time of this writing:
V8 5.4 is currently shipping as part of Chromium stable. This branch was created approx. 6 weeks before from when V8 5.3 shipped as stable.
V8 5.5 is currently in beta. It will be promoted to stable next; approximately 6 weeks after V8 5.4 shipped as stable.
V8 tip-of-tree corresponds to V8 5.6. This branch gets regularly released as part of the Chromium canary builds. This branch will be promoted to beta next when V8 5.5 ships as stable.
All older branches are abandoned and are not maintained by the V8 team.
V8 merge process overview
The process for backporting bug fixes to active branches is officially documented on the V8 wiki. The summary of the process is:
V8 only supports active branches. There is no testing done on any branches older than the current
A fix needing backport is tagged tag. This can be done by anyone interested in getting the fix backported. Issues with this tag are reviewed by the V8 team regularly as candidates for backporting.
Fixes need some 'baking time' before they can be approved for backporting. This means waiting a few days to ensure that no issues are detected on the canary/beta builds.
Once ready, the issue is tagged and one can do the actual merge by using the scripts on the wiki page.
Merge requests to an abandoned branch will be rejected.
Only bug fixes are accepted for backporting
Node.js Support Requirements
At any given time Node.js needs to be maintaining a few different V8 branches for the various Current, LTS, and nightly releases. At present this list includes the following branches1:
Release Support Start Support End V8 version V8 branch released V8 branch abandoned
The versions of V8 used in Node.js v4.x, v6.x, and 8.x have already been abandoned by upstream V8. However, Node.js needs to continue supporting these branches for many months (Current branches) or several years (LTS branches).
Once a bug in Node.js has been identified to be caused by V8, the first step is to identify the versions of Node.js and V8 affected. The bug may be present in multiple different locations, each of which follows a slightly different process.
Unfixed bugs. The bug exists in the V8 master branch.
Fixed, but needs backport. The bug may need porting to one or more branches.
Backporting to active branches.
Backporting to abandoned branches.
Backports identified by the V8 team. Bugs identified by upstream V8 that we haven't encountered in Node.js yet.
Unfixed Upstream Bugs
If the bug can be reproduced on the [Node.js branch], Chromium canary, or V8 tip-of-tree, and the test case is valid, then the bug needs to be fixed upstream first.
Start by opening a bug upstream using this template.
Make sure to include a link to the corresponding Node.js issue (if one exists).
If the fix is simple enough, you may fix it yourself; contributions are welcome.
V8's build waterfall tests your change.
Once the bug is fixed it may still need backporting, if it exists in other V8 branches that are still active or are branches that Node.js cares about. Follow the process for backporting below.
Backporting to Active Branches
If the bug exists in any of the active V8 branches, we may need to get the fix backported. At any given time there are two active branches (beta and stable) in addition to master. The following steps are needed to backport the fix:
Identify which version of V8 the bug was fixed in.
Identify if any active V8 branches still contain the bug:
A tracking bug is needed to request a backport.
If there isn't already a V8 bug tracking the fix, open a new merge request bug using this Node.js specific template.
If a bug already exists
Add a reference to the GitHub issue.
Attach labels to the bug for any active branches that still contain the bug. Add to the cc list.
Once the merge has been approved, it should be merged using the merge script documented in the V8 wiki. Merging requires commit access to the V8 repository. If you don't have commit access you can indicate someone on the V8 team can do the merge for you.
It is possible that the merge request may not get approved, for example if it is considered to be a feature or otherwise too risky for V8 stable. In such cases we float the patch on the Node.js side. See the process on 'Backporting to Abandoned branches'.
Once the fix has been merged upstream, it can be picked up during an update of the V8 branch (see below).
Backporting to Abandoned Branches
Abandoned V8 branches are supported in the Node.js repository. The fix needs to be cherry-picked in the Node.js repository and V8-CI must test the change.
For each abandoned V8 branch corresponding to an LTS branch that is affected by the bug:
Checkout a branch off the appropriate branch (e.g. to fix an issue in V8 5.1).
Cherry-pick the commit(s) from the V8 repository.
On Node.js < 9.0.0: Increase the patch level version in. This will not cause any problems with versioning because V8 will not publish other patches for this branch, so Node.js can effectively bump the patch version.
On Node.js >= 9.0.0: Increase the number in
In some cases the patch may require extra effort to merge in case V8 has changed substantially. For important issues we may be able to lean on the V8 team to get help with reimplementing the patch.
Open a cherry-pick PR on nodejs/node targeting the branch and notify the team.
Run the Node.js V8 CI in addition to the Node.js CI. Note: The CI uses the target in the Makefile, which uses to reconstruct a git tree in the deps/v8 directory to run V8 tests.
The tool can be used to simplify this task. Run backport to cherry-pick a commit.