How-to-change-V8-public-API.md - external/github.com/v8/v8.wiki - Git at Google

 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`](https://cs.chromium.org/chromium/src/v8/include/v8config.h?rcl=6a01631187415688fdebf0c6aa5993c7f1b47b6f&l=316) and [`V8_DEPRECATE_SOON`](https://cs.chromium.org/chromium/src/v8/include/v8config.h?rcl=6a01631187415688fdebf0c6aa5993c7f1b47b6f&l=332) macros. For example, let's say we want to rename function `foo` to function `bar`. Then we need to do the following:
   * Add the new function `bar` near the existing function `foo`.
   * Wait until the CL rolls in Chrome. Adjust Chrome to use `bar`.
   * Annotate `foo` with `V8_DEPRECATED("Use bar instead", void foo());`
   * In the same CL adjust the tests that use `foo` to use `bar`.
   * Write in CL motivation for the change and high-level update instructions.
   * Wait until the next V8 branch.
   * Remove function `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.
	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`](https://cs.chromium.org/chromium/src/v8/include/v8config.h?rcl=6a01631187415688fdebf0c6aa5993c7f1b47b6f&l=316) and [`V8_DEPRECATE_SOON`](https://cs.chromium.org/chromium/src/v8/include/v8config.h?rcl=6a01631187415688fdebf0c6aa5993c7f1b47b6f&l=332) macros. For example, let's say we want to rename function `foo` to function `bar`. Then we need to do the following:
	* Add the new function `bar` near the existing function `foo`.
	* Wait until the CL rolls in Chrome. Adjust Chrome to use `bar`.
	* Annotate `foo` with `V8_DEPRECATED("Use bar instead", void foo());`
	* In the same CL adjust the tests that use `foo` to use `bar`.
	* Write in CL motivation for the change and high-level update instructions.
	* Wait until the next V8 branch.
	* Remove function `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.