Skip to content

Commit

Permalink
doc: experimental flag for global accessible APIs
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
legendecas authored and aduh95 committed Sep 12, 2024
1 parent c1cc046 commit 8931f56
Showing 1 changed file with 17 additions and 0 deletions.
17 changes: 17 additions & 0 deletions doc/contributing/collaborator-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 8931f56

Please sign in to comment.