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

doc, meta: organize contributing to Node-API guide 

PR-URL: https://github.com/nodejs/node/pull/53243
Reviewed-By: Gabriel Schulhof <gabrielschulhof@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
pull/53558/head
Aviv Keller 2024-06-22 11:55:02 -05:00 committed by GitHub
parent cba170d883
commit 69abdcd1bd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 47 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
doc/contributing/adding-new-napi-api.md
View File

@ -1,66 +1,52 @@
# Contributing a new API to Node-API # Contributing a new API to Node-API
Node-API is the next-generation ABI-stable API for native addons. Node-API is the ABI-stable API for native addons. We encourage contributions to enhance the API,
While improving the API surface is encouraged and welcomed, the following are while also ensuring compatibility and adherence to guidelines. When adding a new API to Node-API,
a set of principles and guidelines to keep in mind while adding a new please follow these principles and guidelines:
Node-API.
* A new API **must** adhere to Node-API API shape and spirit. ## Core principles
* **Must** be a C API.
* **Must** not throw exceptions.
* **Must** return `napi_status`.
* **Should** consume `napi_env`.
* **Must** operate only on primitive data types, pointers to primitive
data types or opaque handles.
* **Must** be a necessary API and not a nice to have. Convenience APIs
belong in node-addon-api.
* **Must** not change the signature of an existing Node-API API or break
ABI compatibility with other versions of Node.js.
* New API **should** be agnostic towards the underlying JavaScript VM.
* New API PRs **must** have a corresponding documentation update.
* New API PRs **must** be tagged as **node-api**.
* There **must** be at least one test case showing how to use the API.
* There **should** be at least one test case per interesting use of the API.
* There **should** be a sample provided that operates in a realistic way
(operating how a real addon would be written).
* A new API **should** be discussed at the Node-API team meeting.
* A new API addition **must** be signed off by at least two members of
the Node-API team.
* A new API addition **should** be simultaneously implemented in at least
one other VM implementation of Node.js.
* A new API **must** be considered experimental for at least one minor
version release of Node.js before it can be considered for promotion out
of experimental.
* Experimental APIs **must** be documented as such.
* Experimental APIs **must** require an explicit compile-time flag
(`#define`) to be set to opt-in.
* A feature flag of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>` **must**
be added with each experimental feature in order to allow code to
distinguish between experimental features as present in one version of
Node.js versus another.
* Experimental APIs **must** be considered for backport.
* Experimental status exit criteria **must** involve at least the
following:
* A new PR **must** be opened in `nodejs/node` to remove experimental
status. This PR **must** be tagged as **node-api** and **semver-minor**.
* Exiting an API from experimental **must** be signed off by the team.
* If a backport is merited, an API **must** have a down-level
implementation.
* The API **should** be used by a published real-world module. Use of
the API by a real-world published module will contribute favorably
to the decision to take an API out of experimental status.
* The API **must** be implemented in a Node.js implementation with an
alternate VM.
Since the adoption of the policy whereby moving to a later version of Node-API 1. **Adherence to Node-API standards**
from an earlier version may entail rework of existing code, it is possible to * **Must** be a C API.
introduce modifications to already-released Node-APIs, as long as the * **Must** not throw exceptions.
modifications affect neither the ABI nor the API of earlier versions. Such * **Must** return `napi_status`.
modifications **must** be accompanied by an opt-out flag. This provides add-on * **Should** consume `napi_env`.
maintainers who take advantage of the initial compile-time flag to track * **Must** operate on primitive data types, pointers to primitive data types, or opaque handles.
impending changes to Node-API with * **Must** be a necessary API, not a convenience API (which belongs in node-addon-api).
* **Must** not break ABI compatibility with other Node.js versions.
* a quick fix to the breakage caused, 2. **Maintaining VM agnosticism**
* a notification that such breakage is impending, and thus * New APIs **should** be compatible with various JavaScript VMs.
* a buffer to adoption above and beyond the one provided by the initial
compile-time flag. ## Documentation and testing
1. **Documentation**
* PRs introducing new APIs **must** include corresponding documentation updates.
* Experimental APIs **must** be clearly documented as experimental and require an explicit compile-time flag
to opt-in (`#define`).
2. **Testing**
* PRs **must** include at least one test case demonstrating API usage.
* **Should** include test cases for various interesting uses of the API.
* **Should** provide a sample demonstrating realistic usage, similar to a real-world addon.
## Process and approval
1. **Team discussion**
* New APIs **should** be discussed in a Node-API team meeting.
2. **Review and approval**
* A new API addition **must** be signed off by at least two Node-API team members.
* **Should** be implemented in at least one other VM implementation of Node.js.
3. **Experimental phase**
* New APIs **must** be marked as experimental for at least one minor Node.js release before promotion.
* **Must** have a feature flag (`NODE_API_EXPERIMENTAL_HAS_<FEATURE>`) for distinguishing experimental
feature existence.
* **Must** be considered for backporting.
* Exit criteria from experimental status include:
* Opening a PR in `nodejs/node` to remove experimental status, tagged as **node-api** and **semver-minor**.
* Approval by the Node-API team.
* Availability of a down-level implementation if backporting is needed.
* Usage by a published real-world module.
* Implementation in an alternative VM.