daohualiuxiang
/
node
mirror of https://github.com/nodejs/node.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 <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>
pull/54866/head
Chengzhong Wu 2024-09-09 14:57:04 +01:00 committed by GitHub
parent 79a33a7433
commit 23f8ed0617
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 17 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/contributing/collaborator-guide.md
View File

@ -437,6 +437,23 @@ For pull requests introducing new core modules:
* Land with a [Stability Index][] of Experimental. The module must remain * Land with a [Stability Index][] of Experimental. The module must remain
Experimental until a semver-major release. 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 ### Additions to Node-API
Node-API provides an ABI-stable API guaranteed for future Node.js versions. Node-API provides an ABI-stable API guaranteed for future Node.js versions.