1# Node.js Node-API version release process
2
3This document describes the technical aspects of the Node.js Node-API version
4release process.
5
6## Table of contents
7
8* [How to create a release](#how-to-create-a-release)
9  * [0. Pre-release steps](#0-pre-release-steps)
10  * [1. Update the main branch](#1-update-the-main-branch)
11  * [2. Create a new branch for the release](#2-create-a-new-branch-for-the-release)
12  * [3. Update `NODE_API_SUPPORTED_VERSION_MAX`](#3-update-node_api_supported_version_max)
13  * [4. Define `addon_context_register_func`](#4-define-addon_context_register_func)
14  * [5. Update version guards](#5-update-version-guards)
15  * [6. Create release commit](#6-create-release-commit)
16  * [7. Propose release on GitHub](#7-propose-release-on-github)
17  * [8. Ensure that the release branch is stable](#8-ensure-that-the-release-branch-is-stable)
18  * [9. Land the release](#9-land-the-release)
19  * [10. Backport the release](#10-backport-the-release)
20
21## How to create a release
22
23Notes:
24
25* Version strings are listed below as _"vx"_ or _"x"_. Substitute for
26  the release version.
27* Examples will use the integer release version `10`.
28
29### 0. Pre-release steps
30
31Before preparing a Node.js Node-API version release, the Node-API Working Group
32must be notified at least one business day in advance of the expected release.
33
34Node-API Working Group can be contacted best by opening up an issue on the
35[abi-stable-node issue tracker][].
36
37### 1. Update the main Branch
38
39Checkout the staging branch locally.
40
41```console
42$ git remote update
43$ git checkout main
44$ git reset --hard upstream/main
45```
46
47If the staging branch is not up to date relative to `main`, bring the
48appropriate PRs and commits into it.
49
50### 2. Create a new branch for the release
51
52Create a new branch named `node-api-x-proposal`, off the main branch.
53
54```console
55$ git checkout -b node-api-10-proposal upstream/main
56```
57
58### 3. Update `NODE_API_SUPPORTED_VERSION_MAX`
59
60Set the version for the proposed release using the following macros, which are
61already defined in `src/node_version.h`:
62
63```c
64#define NODE_API_SUPPORTED_VERSION_MAX x
65```
66
67> Note: Do not update the `NAPI_VERSION` defined in `src/js_native_api.h`. It
68> is a fixed constant baseline version of Node-API.
69
70### 4. Define `addon_context_register_func`
71
72For each new version of Node-API an `else if` case must be added to
73`get_node_api_context_register_func` in `src/node_api.cc` and the numeric
74literal used in the `static_assert` statement in that function must be updated
75to the new Node-API version.
76
77### 5. Update version guards
78
79#### Step 1. Update define version guards
80
81If this release includes new Node-APIs that were first released in this
82version, the relevant commits should already include the `NAPI_EXPERIMENTAL`
83define guards on the declaration of the new Node-API. Check for these guards
84with:
85
86```console
87grep                           \
88  -E                           \
89  'N(ODE_)?API_EXPERIMENTAL'   \
90  src/js_native_api{_types,}.h \
91  src/node_api{_types,}.h
92```
93
94and update the define version guards with the release version:
95
96```diff
97- #ifdef NAPI_EXPERIMENTAL
98+ #if NAPI_VERSION >= 10
99
100  NAPI_EXTERN napi_status NAPI_CDECL
101  node_api_function(napi_env env);
102
103- #endif  // NAPI_EXPERIMENTAL
104+ #endif  // NAPI_VERSION >= 10
105```
106
107Remove any feature flags of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>`.
108
109Remove any additional `NODE_API_EXPERIMENTAL_*` guards along with
110`NAPI_EXPERIMENTAL`.
111
112Also, update the Node-API version value of the `napi_get_version` test in
113`test/js-native-api/test_general/test.js` with the release version `x`:
114
115```diff
116  // Test version management functions
117- assert.strictEqual(test_general.testGetVersion(), 9);
118+ assert.strictEqual(test_general.testGetVersion(), 10);
119```
120
121#### Step 2. Update runtime version guards
122
123If this release includes runtime behavior version guards, the relevant commits
124should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check
125for these guards with:
126
127```console
128grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
129```
130
131and substitute this guard version with the release version `x`.
132
133#### Step 3. Update test version guards
134
135If this release includes add-on tests for the new Node-APIs, the relevant
136commits should already include `NAPI_EXPERIMENTAL` definition for the tests.
137Check for these definitions with:
138
139```console
140grep                                    \
141  -E                                    \
142  'N(ODE_)?API_EXPERIMENTAL'            \
143  test/node-api/*/{*.{h,c},binding.gyp} \
144  test/js-native-api/*/{*.{h,c},binding.gyp}
145```
146
147and substitute the `NAPI_EXPERIMENTAL` with the release version
148`NAPI_VERSION x`;
149
150```diff
151- #define NAPI_EXPERIMENTAL
152+ #define NAPI_VERSION 10
153```
154
155Remove any `NODE_API_EXPERIMENTAL_*` flags.
156
157#### Step 4. Update document
158
159If this release includes new Node-APIs that were first released in this
160version and are necessary to document, the relevant commits should already
161have documented the new Node-API.
162
163For all Node-API functions and types with define guards updated in Step 1,
164in `doc/api/n-api.md`, add the `napiVersion: x` metadata to the Node-API types
165and functions that are released in the version, and remove the experimental
166stability banner:
167
168```diff
169  #### node_api_function
170  <!-- YAML
171  added:
172    - v1.2.3
173+ napiVersion: 10
174  -->
175
176- > Stability: 1 - Experimental
177```
178
179#### Step 5. Update change history
180
181If this release includes new Node-APIs runtime version guards that were first
182released in this version and are necessary to document, the relevant commits
183should already have documented the new behavior in a "Change History" section.
184
185For all runtime version guards updated in Step 2, check for these definitions
186with:
187
188```console
189grep NAPI_EXPERIMENTAL doc/api/n-api.md
190```
191
192In `doc/api/n-api.md`, update the `experimental` change history item to be the
193released version `x`:
194
195```diff
196  Change History:
197
198- * experimental (`NAPI_EXPERIMENTAL` is defined):
199+ * version 10:
200```
201
202### 6. Create release commit
203
204When committing these to git, use the following message format:
205
206```text
207node-api: define version x
208```
209
210### 7. Propose release on GitHub
211
212Create a pull request targeting the `main` branch. These PRs should be left
213open for at least 24 hours, and can be updated as new commits land.
214
215If you need any additional information about any of the commits, this PR is a
216good place to @-mention the relevant contributors.
217
218Tag the PR with the `notable-change` label, and @-mention the GitHub team
219@nodejs/node-api and @nodejs/node-api-implementer.
220
221### 8. Ensure that the release branch is stable
222
223Run a **[`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/)**
224test run to ensure that the build is stable and the HEAD commit is ready for
225release.
226
227### 9. Land the release
228
229See the steps documented in [Collaborator Guide - Landing a PR][] to land the
230PR.
231
232### 10. Backport the release
233
234Consider backporting the release to all LTS versions following the steps
235documented in the [backporting guide][].
236
237[Collaborator Guide - Landing a PR]: ./collaborator-guide.md#landing-pull-requests
238[abi-stable-node issue tracker]: https://github.com/nodejs/abi-stable-node/issues
239[backporting guide]: backporting-to-release-lines.md
240