Commit ec38f3d
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1,66 +1,52 @@ | |||
| 1 | 1 | # Contributing a new API to Node-API | |
| 2 | 2 | ||
| 3 | - Node-API is the next-generation ABI-stable API for native addons. | ||
| 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 | - Node-API. | ||
| 3 | + Node-API is the ABI-stable API for native addons. We encourage contributions to enhance the API, | ||
| 4 | + while also ensuring compatibility and adherence to guidelines. When adding a new API to Node-API, | ||
| 5 | + please follow these principles and guidelines: | ||
| 7 | 6 | ||
| 8 | - * A new API **must** adhere to Node-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 | - data types 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 Node-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 **node-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 Node-API team meeting. | ||
| 27 | - * A new API addition **must** be signed off by at least two members of | ||
| 28 | - the Node-API team. | ||
| 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 | - * A feature flag of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>` **must** | ||
| 38 | - be added with each experimental feature in order to allow code to | ||
| 39 | - distinguish between experimental features as present in one version of | ||
| 40 | - Node.js versus another. | ||
| 41 | - * Experimental APIs **must** be considered for backport. | ||
| 42 | - * Experimental status exit criteria **must** involve at least the | ||
| 43 | - following: | ||
| 44 | - * A new PR **must** be opened in `nodejs/node` to remove experimental | ||
| 45 | - status. This PR **must** be tagged as **node-api** and **semver-minor**. | ||
| 46 | - * Exiting an API from experimental **must** be signed off by the team. | ||
| 47 | - * If a backport is merited, an API **must** have a down-level | ||
| 48 | - implementation. | ||
| 49 | - * The API **should** be used by a published real-world module. Use of | ||
| 50 | - the API by a real-world published module will contribute favorably | ||
| 51 | - to the decision to take an API out of experimental status. | ||
| 52 | - * The API **must** be implemented in a Node.js implementation with an | ||
| 53 | - alternate VM. | ||
| 7 | + ## Core principles | ||
| 54 | 8 | ||
| 55 | - Since the adoption of the policy whereby moving to a later version of Node-API | ||
| 56 | - from an earlier version may entail rework of existing code, it is possible to | ||
| 57 | - introduce modifications to already-released Node-APIs, as long as the | ||
| 58 | - modifications affect neither the ABI nor the API of earlier versions. Such | ||
| 59 | - modifications **must** be accompanied by an opt-out flag. This provides add-on | ||
| 60 | - maintainers who take advantage of the initial compile-time flag to track | ||
| 61 | - impending changes to Node-API with | ||
| 9 | + 1. **Adherence to Node-API standards** | ||
| 10 | + * **Must** be a C API. | ||
| 11 | + * **Must** not throw exceptions. | ||
| 12 | + * **Must** return `napi_status`. | ||
| 13 | + * **Should** consume `napi_env`. | ||
| 14 | + * **Must** operate on primitive data types, pointers to primitive data types, or opaque handles. | ||
| 15 | + * **Must** be a necessary API, not a convenience API (which belongs in node-addon-api). | ||
| 16 | + * **Must** not break ABI compatibility with other Node.js versions. | ||
| 62 | 17 | ||
| 63 | - * a quick fix to the breakage caused, | ||
| 64 | - * a notification that such breakage is impending, and thus | ||
| 65 | - * a buffer to adoption above and beyond the one provided by the initial | ||
| 66 | - compile-time flag. | ||
| 18 | + 2. **Maintaining VM agnosticism** | ||
| 19 | + * New APIs **should** be compatible with various JavaScript VMs. | ||
| 20 | + | ||
| 21 | + ## Documentation and testing | ||
| 22 | + | ||
| 23 | + 1. **Documentation** | ||
| 24 | + * PRs introducing new APIs **must** include corresponding documentation updates. | ||
| 25 | + * Experimental APIs **must** be clearly documented as experimental and require an explicit compile-time flag | ||
| 26 | + to opt-in (`#define`). | ||
| 27 | + | ||
| 28 | + 2. **Testing** | ||
| 29 | + * PRs **must** include at least one test case demonstrating API usage. | ||
| 30 | + * **Should** include test cases for various interesting uses of the API. | ||
| 31 | + * **Should** provide a sample demonstrating realistic usage, similar to a real-world addon. | ||
| 32 | + | ||
| 33 | + ## Process and approval | ||
| 34 | + | ||
| 35 | + 1. **Team discussion** | ||
| 36 | + * New APIs **should** be discussed in a Node-API team meeting. | ||
| 37 | + | ||
| 38 | + 2. **Review and approval** | ||
| 39 | + * A new API addition **must** be signed off by at least two Node-API team members. | ||
| 40 | + * **Should** be implemented in at least one other VM implementation of Node.js. | ||
| 41 | + | ||
| 42 | + 3. **Experimental phase** | ||
| 43 | + * New APIs **must** be marked as experimental for at least one minor Node.js release before promotion. | ||
| 44 | + * **Must** have a feature flag (`NODE_API_EXPERIMENTAL_HAS_<FEATURE>`) for distinguishing experimental | ||
| 45 | + feature existence. | ||
| 46 | + * **Must** be considered for backporting. | ||
| 47 | + * Exit criteria from experimental status include: | ||
| 48 | + * Opening a PR in `nodejs/node` to remove experimental status, tagged as **node-api** and **semver-minor**. | ||
| 49 | + * Approval by the Node-API team. | ||
| 50 | + * Availability of a down-level implementation if backporting is needed. | ||
| 51 | + * Usage by a published real-world module. | ||
| 52 | + * Implementation in an alternative VM. | ||
0 commit comments