mirror of
https://github.com/nodejs/node.git
synced 2024-11-28 14:33:11 +01:00
69abdcd1bd
PR-URL: https://github.com/nodejs/node/pull/53243 Reviewed-By: Gabriel Schulhof <gabrielschulhof@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
53 lines
2.3 KiB
Markdown
53 lines
2.3 KiB
Markdown
# Contributing a new API to 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:
|
|
|
|
## Core principles
|
|
|
|
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.
|
|
|
|
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.
|