Commit 0c0412e
doc: move NODE_MODULE_VERSION in release guide
Move the section on `NODE_MODULE_VERSION` into the section for
major releases as it should only be updated for a major release.
Add a note to remove the `-pre` suffix from the registry for the
release commit.
PR-URL: #39544
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Beth Griggs <bgriggs@redhat.com>
Reviewed-By: Danielle Adams <adamzdanielle@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>1 parent 5df74f9 commit 0c0412e
1 file changed
Lines changed: 30 additions & 28 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -243,34 +243,6 @@ be produced with a version string that does not have a trailing pre-release tag: | |||
| 243 | 243 | #define NODE_VERSION_IS_RELEASE 1 | |
| 244 | 244 | ``` | |
| 245 | 245 | ||
| 246 | - **Also consider whether to bump `NODE_MODULE_VERSION`**: | ||
| 247 | - | ||
| 248 | - This macro is used to signal an ABI version for native addons. It currently has | ||
| 249 | - two common uses in the community: | ||
| 250 | - | ||
| 251 | - * Determining what API to work against for compiling native addons, e.g. | ||
| 252 | - [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for | ||
| 253 | - much of what it wraps. | ||
| 254 | - * Determining the ABI for downloading pre-built binaries of native addons, e.g. | ||
| 255 | - [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as | ||
| 256 | - exposed via `process.versions.modules` to help determine the appropriate | ||
| 257 | - binary to download at install-time. | ||
| 258 | - | ||
| 259 | - The general rule is to bump this version when there are _breaking ABI_ changes | ||
| 260 | - and also if there are non-trivial API changes. The rules are not yet strictly | ||
| 261 | - defined, so if in doubt, please confer with someone that will have a more | ||
| 262 | - informed perspective, such as a member of the NAN team. | ||
| 263 | - | ||
| 264 | - A registry of currently used `NODE_MODULE_VERSION` values is maintained at | ||
| 265 | - <https://github.com/nodejs/node/blob/HEAD/doc/abi_version_registry.json>. | ||
| 266 | - When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed | ||
| 267 | - in the registry. Also include a change to the registry in your commit to | ||
| 268 | - reflect the newly used value. | ||
| 269 | - | ||
| 270 | - It is current TSC policy to bump major version when ABI changes. If you | ||
| 271 | - see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. | ||
| 272 | - Commits may need to be reverted or a major version bump may need to happen. | ||
| 273 | - | ||
| 274 | 246 | ### 4. Update the changelog | |
| 275 | 247 | ||
| 276 | 248 | #### Step 1: Collect the formatted list of changes | |
@@ -838,6 +810,36 @@ Notify the `@nodejs/npm` team in the release proposal PR to inform them of the | |||
| 838 | 810 | upcoming release. `npm` maintains a list of [supported versions](https://github.com/npm/cli/blob/latest/lib/utils/unsupported.js#L3) | |
| 839 | 811 | that will need updating to include the new major release. | |
| 840 | 812 | ||
| 813 | + ### Update `NODE_MODULE_VERSION` | ||
| 814 | + | ||
| 815 | + This macro in `src/node_version.h` is used to signal an ABI version for native | ||
| 816 | + addons. It currently has two common uses in the community: | ||
| 817 | + | ||
| 818 | + * Determining what API to work against for compiling native addons, e.g. | ||
| 819 | + [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for | ||
| 820 | + much of what it wraps. | ||
| 821 | + * Determining the ABI for downloading pre-built binaries of native addons, e.g. | ||
| 822 | + [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as | ||
| 823 | + exposed via `process.versions.modules` to help determine the appropriate | ||
| 824 | + binary to download at install-time. | ||
| 825 | + | ||
| 826 | + The general rule is to bump this version when there are _breaking ABI_ changes | ||
| 827 | + and also if there are non-trivial API changes. The rules are not yet strictly | ||
| 828 | + defined, so if in doubt, please confer with someone that will have a more | ||
| 829 | + informed perspective, such as a member of the NAN team. | ||
| 830 | + | ||
| 831 | + A registry of currently used `NODE_MODULE_VERSION` values is maintained at | ||
| 832 | + <https://github.com/nodejs/node/blob/HEAD/doc/abi_version_registry.json>. | ||
| 833 | + When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed | ||
| 834 | + in the registry. Also include a change to the registry in your commit to | ||
| 835 | + reflect the newly used value. Ensure that the release commit removes the | ||
| 836 | + `-pre` suffix for the major version being prepared. | ||
| 837 | + | ||
| 838 | + It is current TSC policy to bump major version when ABI changes. If you | ||
| 839 | + see a need to bump `NODE_MODULE_VERSION` outside of a majore release then | ||
| 840 | + you should consult the TSC. Commits may need to be reverted or a major | ||
| 841 | + version bump may need to happen. | ||
| 842 | + | ||
| 841 | 843 | ### Test releases and release candidates | |
| 842 | 844 | ||
| 843 | 845 | Test builds should be generated from the `vN.x-proposal` branch starting at | |
0 commit comments