Skip to content

Commit 8931f56

Browse files
legendecasaduh95
authored andcommitted
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: #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>
1 parent c1cc046 commit 8931f56

File tree

1 file changed

+17
-0
lines changed

1 file changed

+17
-0
lines changed

doc/contributing/collaborator-guide.md

+17
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,23 @@ For pull requests introducing new core modules:
437437
* Land with a [Stability Index][] of Experimental. The module must remain
438438
Experimental until a semver-major release.
439439

440+
### Introducing new APIs on the global scope
441+
442+
Exposing new APIs to the global scope that are available without
443+
an `import` or `require` call, including introducing new interfaces on
444+
`globalThis` like `globalThis.navigator`, and adding new properties on
445+
interfaces on `globalThis` like well known symbols, could break feature
446+
detection and Node.js environment detection.
447+
448+
Exposing new APIs to the global scope unconditionally without any CLI
449+
flags must always be labeled as `semver-major`. The `semver-major` label may
450+
be waived through the regular TSC consensus process.
451+
452+
It is recommended to start with exposing APIs to the global scope with an
453+
experimental CLI flag `--experimental-<feature-name>`, without being labeled as
454+
`semver-major`. When the new APIs are feature complete, turn the flag on by
455+
default with a CLI flag `--no-experimental-<feature-name>` to opt-out.
456+
440457
### Additions to Node-API
441458

442459
Node-API provides an ABI-stable API guaranteed for future Node.js versions.

0 commit comments

Comments
 (0)