From 23f8ed06176a93f7026c6983abb3e12f10bfc1d3 Mon Sep 17 00:00:00 2001 From: Chengzhong Wu Date: Mon, 9 Sep 2024 14:57:04 +0100 Subject: [PATCH] doc: experimental flag for global accessible APIs Explicitly document that adding an API to the global scope requires `semver-major` label. Waiving the `semver-major` requires a regular TSC consensus process. PR-URL: https://github.com/nodejs/node/pull/54330 Refs: https://github.com/nodejs/node/pull/54329 Reviewed-By: James M Snell Reviewed-By: Antoine du Hamel Reviewed-By: Matteo Collina Reviewed-By: Michael Dawson --- doc/contributing/collaborator-guide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index a7021db9b2a..5c3b8d14ba8 100644 --- a/doc/contributing/collaborator-guide.md +++ b/doc/contributing/collaborator-guide.md @@ -437,6 +437,23 @@ For pull requests introducing new core modules: * Land with a [Stability Index][] of Experimental. The module must remain Experimental until a semver-major release. +### Introducing new APIs on the global scope + +Exposing new APIs to the global scope that are available without +an `import` or `require` call, including introducing new interfaces on +`globalThis` like `globalThis.navigator`, and adding new properties on +interfaces on `globalThis` like well known symbols, could break feature +detection and Node.js environment detection. + +Exposing new APIs to the global scope unconditionally without any CLI +flags must always be labeled as `semver-major`. The `semver-major` label may +be waived through the regular TSC consensus process. + +It is recommended to start with exposing APIs to the global scope with an +experimental CLI flag `--experimental-`, without being labeled as +`semver-major`. When the new APIs are feature complete, turn the flag on by +default with a CLI flag `--no-experimental-` to opt-out. + ### Additions to Node-API Node-API provides an ABI-stable API guaranteed for future Node.js versions.