From 1918241190566fa5fd7209ebd78b91cda1e34286 Mon Sep 17 00:00:00 2001 From: Chengzhong Wu Date: Fri, 19 May 2023 10:21:10 +0800 Subject: [PATCH] doc: document node-api version process PR-URL: https://github.com/nodejs/node/pull/47972 Fixes: https://github.com/nodejs/node/issues/47664 Reviewed-By: Rafael Gonzaga Reviewed-By: Michael Dawson Reviewed-By: Gabriel Schulhof --- doc/contributing/releases-node-api.md | 224 ++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 doc/contributing/releases-node-api.md diff --git a/doc/contributing/releases-node-api.md b/doc/contributing/releases-node-api.md new file mode 100644 index 00000000000000..b5cbb321cc4b74 --- /dev/null +++ b/doc/contributing/releases-node-api.md @@ -0,0 +1,224 @@ +# Node.js Node-API version release process + +This document describes the technical aspects of the Node.js Node-API version +release process. + +## Table of contents + +* [How to create a release](#how-to-create-a-release) + * [0. Pre-release steps](#0-pre-release-steps) + * [1. Update the main branch](#1-update-the-main-branch) + * [2. Create a new branch for the release](#2-create-a-new-branch-for-the-release) + * [3. Update `NAPI_VERSION`](#3-update-napi_version) + * [4. Define `addon_context_register_func`](#4-define-addon_context_register_func) + * [5. Update version guards](#5-update-version-guards) + * [6. Create release commit](#6-create-release-commit) + * [7. Propose release on GitHub](#7-propose-release-on-github) + * [8. Ensure that the release branch is stable](#8-ensure-that-the-release-branch-is-stable) + * [9. Land the release](#9-land-the-release) + * [10. Backport the release](#10-backport-the-release) + +## How to create a release + +Notes: + +* Version strings are listed below as _"vx"_ or _"x"_. Substitute for + the release version. +* Examples will use the integer release version `10`. + +### 0. Pre-release steps + +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][]. + +### 1. Update the main Branch + +Checkout the staging branch locally. + +```console +$ git remote update +$ git checkout main +$ git reset --hard upstream/main +``` + +If the staging branch is not up to date relative to `main`, bring the +appropriate PRs and commits into it. + +### 2. Create a new branch for the release + +Create a new branch named `node-api-x-proposal`, off the main branch. + +```console +$ git checkout -b node-api-10-proposal upstream/main +``` + +### 3. Update `NAPI_VERSION` + +Set the version for the proposed release using the following macros, which are +already defined in `src/node_version.h`: + +```c +#define NAPI_VERSION x +``` + +> Note: Do not update the `NAPI_VERSION` defined in `src/js_native_api.h`. It +> is a fixed constant baseline version of Node-API. + +### 4. Define `addon_context_register_func` + +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. + +### 5. Update version guards + +#### Step 1. Update define version guards + +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: + +```console +grep NAPI_EXPERIMENTAL src/js_native_api{_types,}.h src/node_api{_types,}.h +``` + +and update the define version guards with the release version: + +```diff +- #ifdef NAPI_EXPERIMENTAL ++ #if NAPI_VERSION >= 10 + + NAPI_EXTERN napi_status NAPI_CDECL + node_api_function(napi_env env); + +- #endif // NAPI_EXPERIMENTAL ++ #endif // NAPI_VERSION >= 10 +``` + +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`: + +```diff + // Test version management functions +- assert.strictEqual(test_general.testGetVersion(), 9); ++ assert.strictEqual(test_general.testGetVersion(), 10); +``` + +#### Step 2. Update runtime version guards + +If this release includes runtime behavior version guards, the relevant commits +should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check +for these guards with: + +```console +grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc +``` + +and substitute this guard version with the release version `x`. + +#### Step 3. Update test version guards + +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: + +```console +grep NAPI_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`; + +```diff +- #define NAPI_EXPERIMENTAL ++ #define NAPI_VERSION 10 +``` + +#### Step 4. Update document + +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: + +```diff + #### node_api_function + + +- > Stability: 1 - Experimental +``` + +#### Step 5. Update change history + +If 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: + +```console +grep NAPI_EXPERIMENTAL doc/api/n-api.md +``` + +In `doc/api/n-api.md`, update the `experimental` change history item to be the +released version `x`: + +```diff + Change History: + +- * experimental (`NAPI_EXPERIMENTAL` is defined): ++ * version 10: +``` + +### 6. Create release commit + +When committing these to git, use the following message format: + +```text +node-api: define version x +``` + +### 7. Propose release on GitHub + +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. + +### 8. Ensure that the release branch is stable + +Run a **[`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/)** +test run to ensure that the build is stable and the HEAD commit is ready for +release. + +### 9. Land the release + +See the steps documented in [Collaborator Guide - Landing a PR][] to land the +PR. + +### 10. Backport the release + +Consider backporting the release to all LTS versions following the steps +documented in the [backporting guide][]. + +[Collaborator Guide - Landing a PR]: ./collaborator-guide.md#landing-pull-requests +[abi-stable-node issue tracker]: https://github.com/nodejs/abi-stable-node/issues +[backporting guide]: backporting-to-release-lines.md