V8 is used by many different embedders: Chrome, NodeJS, gjstest, etc. When changing V8 public API 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 V8_DEPRECATED
and V8_DEPRECATE_SOON
macros. For example, let's say we want to rename function foo
to function bar
. Then we need to do the following:
bar
near the existing function foo
.bar
.foo
with V8_DEPRECATED("Use bar instead", void foo());
foo
to use bar
.foo
.V8_DEPRECATE_SOON
is a softer version of V8_DEPRECATED
. Chrome will not break with it, so step b is not need. V8_DEPRECATE_SOON
is not sufficient for removing the function. You still need to annotate with V8_DEPRECATED
and wait for the next branch before removing the function. V8_DEPRECATED
can be tested using v8_deprecation_warnings
gn flag. V8_DEPRECATE_SOON
can be tested using v8_imminent_deprecation_warnings
.
Changing function signature is unsafe. Use V8_DEPRECATED
and V8_DEPRECATE_SOON
macros as described above.