mirrors/nodejs
mirrors/nodejs
0
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2024-11-30 07:27:22 +01:00
Code Issues Releases Activity
9f71dbc334
nodejs/doc/guides/adding-new-napi-api.md

50 lines
2.6 KiB
Markdown
Raw Normal View History

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: https://github.com/nodejs/node/pull/21877 Refs: https://github.com/nodejs/abi-stable-node/issues/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>
2018-07-19 03:57:23 +02:00
# Contributing a new API to N-API
N-API is Node.js's next generation ABI-stable API for native modules.
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
N-API API.
* A new API **must** adhere to N-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
datatypes 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 N-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 **n-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).
doc: replace _WG_ with _team_ AFAICT, there is no N-API Working Group. There *is* an N-API team, but AFAIK there is no charter etc. (And if I'm wrong and there is, then https://nodejs.org/en/about/working-groups/ needs an update!) PR-URL: https://github.com/nodejs/node/pull/22183 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
2018-08-08 01:23:39 +02:00
* A new API **should** be discussed at the N-API team meeting.
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: https://github.com/nodejs/node/pull/21877 Refs: https://github.com/nodejs/abi-stable-node/issues/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>
2018-07-19 03:57:23 +02:00
* A new API addition **must** be signed off by at least two members of
doc: replace _WG_ with _team_ AFAICT, there is no N-API Working Group. There *is* an N-API team, but AFAIK there is no charter etc. (And if I'm wrong and there is, then https://nodejs.org/en/about/working-groups/ needs an update!) PR-URL: https://github.com/nodejs/node/pull/22183 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
2018-08-08 01:23:39 +02:00
the N-API team.
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: https://github.com/nodejs/node/pull/21877 Refs: https://github.com/nodejs/abi-stable-node/issues/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>
2018-07-19 03:57:23 +02:00
* 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.
* 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 **n-api** and **semver-minor**.
doc: replace _WG_ with _team_ AFAICT, there is no N-API Working Group. There *is* an N-API team, but AFAIK there is no charter etc. (And if I'm wrong and there is, then https://nodejs.org/en/about/working-groups/ needs an update!) PR-URL: https://github.com/nodejs/node/pull/22183 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
2018-08-08 01:23:39 +02:00
* Exiting an API from experimental **must** be signed off by the team.
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: https://github.com/nodejs/node/pull/21877 Refs: https://github.com/nodejs/abi-stable-node/issues/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>
2018-07-19 03:57:23 +02:00
* 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.
Copy Permalink