doc: experimental flag for global accessible APIs

legendecas · targos · commit a6c748fffb2c · 2024-10-02T16:04:13.000+02:00
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: #54330 Refs: #54329 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com>
diff --git 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-<feature-name>`, 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-<feature-name>` to opt-out.
+
 ### Additions to Node-API
 
 Node-API provides an ABI-stable API guaranteed for future Node.js versions.
