This document describes the technical aspects of the Node.js Node-API version release process.
- How to create a release
- 0. Pre-release steps
- 1. Update the main branch
- 2. Create a new branch for the release
- 3. Update
NODE_API_SUPPORTED_VERSION_MAX - 4. Define
addon_context_register_func - 5. Update version guards
- 6. Update version matrix document
- 7. Create release commit
- 8. Propose release on GitHub
- 9. Ensure that the release branch is stable
- 10. Land the release
- 11. Backport the release
Notes:
- Version strings are listed below as "vx" or "x". Substitute for the release version.
- Examples will use the integer release version
10.
Before preparing a Node.js Node-API version release, the Node-API Working Group must be notified at least one business day in advance of the expected release.
Node-API Working Group can be contacted best by opening up an issue on the abi-stable-node issue tracker.
Checkout the staging branch locally.
git remote update
git checkout main
git reset --hard upstream/mainIf the staging branch is not up to date relative to main, bring the
appropriate PRs and commits into it.
Create a new branch named node-api-x-proposal, off the main branch.
git checkout -b node-api-10-proposal upstream/mainSet the version for the proposed release using the following macros, which are
already defined in src/node_version.h:
#define NODE_API_SUPPORTED_VERSION_MAX xNote: Do not update the
NAPI_VERSIONdefined insrc/js_native_api.h. It is a fixed constant baseline version of Node-API.
For each new version of Node-API an else if case must be added to
get_node_api_context_register_func in src/node_api.cc and the numeric
literal used in the static_assert statement in that function must be updated
to the new Node-API version.
If this release includes new Node-APIs that were first released in this
version, the relevant commits should already include the NAPI_EXPERIMENTAL
define guards on the declaration of the new Node-API. Check for these guards
with:
grep \
-nHE \
'N(ODE_)?API_EXPERIMENTAL' \
src/js_native_api{_types,}.h \
src/node_api{_types,}.hand update the define version guards with the release version:
- #ifdef NAPI_EXPERIMENTAL
+ #if NAPI_VERSION >= 11
NAPI_EXTERN napi_status NAPI_CDECL
node_api_function(napi_env env);
- #endif // NAPI_EXPERIMENTAL
+ #endif // NAPI_VERSION >= 11Remove any feature flags of the form NODE_API_EXPERIMENTAL_HAS_<FEATURE>.
Remove any additional NODE_API_EXPERIMENTAL_* guards along with
NAPI_EXPERIMENTAL.
Also, update the Node-API version value of the napi_get_version test in
test/js-native-api/test_general/test.js with the release version x:
// Test version management functions
- assert.strictEqual(test_general.testGetVersion(), 9);
+ assert.strictEqual(test_general.testGetVersion(), 10);If this release includes runtime behavior version guards, the relevant commits
should already include the NAPI_VERSION_EXPERIMENTAL guard for the change.
Check for these guards with:
grep -nH NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.ccand substitute this guard version with the release version x.
If this release includes add-on tests for the new Node-APIs, the relevant
commits should already include NAPI_EXPERIMENTAL definition for the tests.
Check for these definitions with:
grep \
-nHE \
'N(ODE_)?API_EXPERIMENTAL' \
test/node-api/*/{*.{h,c},binding.gyp} \
test/js-native-api/*/{*.{h,c},binding.gyp}and substitute the NAPI_EXPERIMENTAL with the release version
NAPI_VERSION x;
- #define NAPI_EXPERIMENTAL
+ #define NAPI_VERSION 10Remove any NODE_API_EXPERIMENTAL_* flags.
If this release includes new Node-APIs that were first released in this version and are necessary to document, the relevant commits should already have documented the new Node-API.
For all Node-API functions and types with define guards updated in Step 1,
in doc/api/n-api.md, add the napiVersion: x metadata to the Node-API types
and functions that are released in the version, and remove the experimental
stability banner:
#### node_api_function
<!-- YAML
added:
- v1.2.3
+ napiVersion: 11
-->
- > Stability: 1 - ExperimentalIf this release includes new Node-APIs runtime version guards that were first released in this version and are necessary to document, the relevant commits should already have documented the new behavior in a "Change History" section.
For all runtime version guards updated in Step 2, check for these definitions with:
grep -nH NAPI_EXPERIMENTAL doc/api/n-api.mdIn doc/api/n-api.md, update the experimental change history item to be the
released version x:
Change History:
- * experimental (`NAPI_EXPERIMENTAL` is defined):
+ * version 10:Add a new row in the version matrix for the new version:
<tr>
<th scope="row">10</th>
<td>vREPLACEME+ and all later versions</td>
</tr>
In this case, use REPLACEME as a placeholder for the Node.js version to be released.
It will be updated in a Node.js version release.
When committing these to git, use the following message format:
node-api: define version x
Create a pull request targeting the main branch. These PRs should be left
open for at least 24 hours, and can be updated as new commits land.
If you need any additional information about any of the commits, this PR is a good place to @-mention the relevant contributors.
Tag the PR with the notable-change label, and @-mention the GitHub team
@nodejs/node-api and @nodejs/node-api-implementer.
Run a node-test-pull-request
test run to ensure that the build is stable and the HEAD commit is ready for
release.
See the steps documented in Collaborator Guide - Landing a PR to land the PR.
Consider backporting the release to all LTS versions following the steps documented in the backporting guide.
Additionally, update the version matrix for the backported version if necessary.