V8’s public API
This document discusses the stability of V8’s public API, and how developers can make changes to it.
API stability #
If V8 in a Chromium canary turns out to be crashy, it gets rolled back to the V8 version of the previous canary. It is therefore important to keep V8’s API compatible from one canary version to the next.
We continuously run a bot that signals API stability violations. It compiles Chromium’s HEAD with V8’s current canary version.
Failures of this bot are currently only FYI and no action is required. The blame list can be used to easily identify dependent CLs in case of a rollback.
If you break this bot, be reminded to increase the window between a V8 change and a dependent Chromium change next time.
How to change V8’s public API #
V8 is used by many different embedders: Chrome, Node.js, gjstest, etc. When changing V8’s public API (basically the files under the
include/ directory) we need to ensure that the embedders can smoothly update to the new V8 version. In particular, we cannot assume that an embedder updates to the new V8 version and adjusts their code to the new API in one atomic change.
The embedder should be able to adjust their code to the new API while still using the previous version of V8. All instructions below follow from this rule.
Adding new types, constants, and functions is safe with one caveat: do not add a new pure virtual function to an existing class. New virtual functions should have default implementation.
Adding a new parameter to a function is safe if the parameter has the default value.
Removing or renaming types, constants, functions is unsafe. Use the
V8_DEPRECATE_SOONmacros, which causes compile-time warnings when the deprecated methods are called by the embedder. For example, let’s say we want to rename function
bar. Then we need to do the following:
- Add the new function
barnear the existing function
- Wait until the CL rolls in Chrome. Adjust Chrome to use
V8_DEPRECATED("Use bar instead", void foo());
- In the same CL adjust the tests that use
- Write in CL motivation for the change and high-level update instructions.
- Wait until the next V8 branch.
- Remove function
V8_DEPRECATE_SOONis a softer version of
V8_DEPRECATED. Chrome will not break with it, so step b is not need.
V8_DEPRECATE_SOONis not sufficient for removing the function.
You still need to annotate with
V8_DEPRECATEDand wait for the next branch before removing the function.
V8_DEPRECATEDcan be tested using the
V8_DEPRECATE_SOONcan be tested using
- Add the new function
Changing function signatures is unsafe. Use the
V8_DEPRECATE_SOONmacros as described above.
We maintain a document mentioning important API changes for each V8 version.