Nodejs/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2024-11-21 10:59:27 +00:00
Code Issues Actions 25 Packages Projects Releases Wiki Activity

doc, meta: organize contributing to Node-API guide

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/53243
Reviewed-By: Gabriel Schulhof <gabrielschulhof@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
This commit is contained in:
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
Node-API is the next-generation ABI-stable API for native addons.
While improving the API surface is encouraged and welcomed, the following are
a set of principles and guidelines to keep in mind while adding a new
Node-API.
Node-API is the ABI-stable API for native addons. We encourage contributions to enhance the API,
while also ensuring compatibility and adherence to guidelines. When adding a new API to Node-API,
please follow these principles and guidelines:
* A new API **must** adhere to Node-API API shape and spirit.
* **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.
## Core principles
Since the adoption of the policy whereby moving to a later version of Node-API
from an earlier version may entail rework of existing code, it is possible to
introduce modifications to already-released Node-APIs, as long as the
modifications affect neither the ABI nor the API of earlier versions. Such
modifications **must** be accompanied by an opt-out flag. This provides add-on
maintainers who take advantage of the initial compile-time flag to track
impending changes to Node-API with
1. **Adherence to Node-API standards**
* **Must** be a C API.
* **Must** not throw exceptions.
* **Must** return `napi_status`.
* **Should** consume `napi_env`.
* **Must** operate on primitive data types, pointers to primitive data types, or opaque handles.
* **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,
* a notification that such breakage is impending, and thus
* a buffer to adoption above and beyond the one provided by the initial
compile-time flag.
2. **Maintaining VM agnosticism**
* New APIs **should** be compatible with various JavaScript VMs.
## 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.