Commit 5b0c451
doc: add guide for updating N-API API surface
This adds a new guide that outlines the principles and guidelines
for contributing a new API to the N-API surface. These guidelines
were formulated based on discussions in the API working group.
PR-URL: #21877
Refs: nodejs/abi-stable-node#301
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>1 parent f868415 commit 5b0c451
1 file changed
Lines changed: 50 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -0,0 +1,50 @@ | |||
| 1 | + # Contributing a new API to N-API | ||
| 2 | + | ||
| 3 | + N-API is Node.js's next generation ABI-stable API for native modules. | ||
| 4 | + While improving the API surface is encouraged and welcomed, the following are | ||
| 5 | + a set of principles and guidelines to keep in mind while adding a new | ||
| 6 | + N-API API. | ||
| 7 | + | ||
| 8 | + * A new API **must** adhere to N-API API shape and spirit. | ||
| 9 | + * **Must** be a C API. | ||
| 10 | + * **Must** not throw exceptions. | ||
| 11 | + * **Must** return `napi_status`. | ||
| 12 | + * **Should** consume `napi_env`. | ||
| 13 | + * **Must** operate only on primitive data types, pointers to primitive | ||
| 14 | + datatypes or opaque handles. | ||
| 15 | + * **Must** be a necessary API and not a nice to have. Convenience APIs | ||
| 16 | + belong in node-addon-api. | ||
| 17 | + * **Must** not change the signature of an existing N-API API or break | ||
| 18 | + ABI compatibility with other versions of Node.js. | ||
| 19 | + * New API **should** be agnostic towards the underlying JavaScript VM. | ||
| 20 | + * New API PRs **must** have a corresponding documentation update. | ||
| 21 | + * New API PRs **must** be tagged as **n-api**. | ||
| 22 | + * There **must** be at least one test case showing how to use the API. | ||
| 23 | + * There **should** be at least one test case per interesting use of the API. | ||
| 24 | + * There **should** be a sample provided that operates in a realistic way | ||
| 25 | + (operating how a real addon would be written). | ||
| 26 | + * A new API **should** be discussed at the N-API working group meeting. | ||
| 27 | + * A new API addition **must** be signed off by at least two members of | ||
| 28 | + the N-API WG. | ||
| 29 | + * A new API addition **should** be simultaneously implemented in at least | ||
| 30 | + one other VM implementation of Node.js. | ||
| 31 | + * A new API **must** be considered experimental for at least one minor | ||
| 32 | + version release of Node.js before it can be considered for promotion out | ||
| 33 | + of experimental. | ||
| 34 | + * Experimental APIs **must** be documented as such. | ||
| 35 | + * Experimental APIs **must** require an explicit compile-time flag | ||
| 36 | + (`#define`) to be set to opt-in. | ||
| 37 | + * Experimental APIs **must** be considered for backport. | ||
| 38 | + * Experimental status exit criteria **must** involve at least the | ||
| 39 | + following: | ||
| 40 | + * A new PR **must** be opened in `nodejs/node` to remove experimental | ||
| 41 | + status. This PR **must** be tagged as **n-api** and **semver-minor**. | ||
| 42 | + * Exiting an API from experimental **must** be signed off by the | ||
| 43 | + working group. | ||
| 44 | + * If a backport is merited, an API **must** have a down-level | ||
| 45 | + implementation. | ||
| 46 | + * The API **should** be used by a published real-world module. Use of | ||
| 47 | + the API by a real-world published module will contribute favorably | ||
| 48 | + to the decision to take an API out of experimental status. | ||
| 49 | + * The API **must** be implemented in a Node.js implementation with an | ||
| 50 | + alternate VM. | ||
0 commit comments