From 8799a134e4cbad1a35ba52f70c87e4bc6bb9ef1a Mon Sep 17 00:00:00 2001 From: Richard Lau Date: Tue, 27 Jul 2021 13:15:02 +0100 Subject: [PATCH] doc: move `NODE_MODULE_VERSION` in release guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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: https://github.com/nodejs/node/pull/39544 Reviewed-By: Michaël Zasso Reviewed-By: Beth Griggs Reviewed-By: Danielle Adams Reviewed-By: James M Snell --- doc/guides/releases.md | 58 ++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/doc/guides/releases.md b/doc/guides/releases.md index 1c4287c9925f90..d3c0712b73768c 100644 --- a/doc/guides/releases.md +++ b/doc/guides/releases.md @@ -243,34 +243,6 @@ be produced with a version string that does not have a trailing pre-release tag: #define NODE_VERSION_IS_RELEASE 1 ``` -**Also consider whether to bump `NODE_MODULE_VERSION`**: - -This macro is used to signal an ABI version for native addons. It currently has -two common uses in the community: - -* Determining what API to work against for compiling native addons, e.g. - [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for - much of what it wraps. -* Determining the ABI for downloading pre-built binaries of native addons, e.g. - [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as - exposed via `process.versions.modules` to help determine the appropriate - binary to download at install-time. - -The general rule is to bump this version when there are _breaking ABI_ changes -and also if there are non-trivial API changes. The rules are not yet strictly -defined, so if in doubt, please confer with someone that will have a more -informed perspective, such as a member of the NAN team. - -A registry of currently used `NODE_MODULE_VERSION` values is maintained at -. -When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed -in the registry. Also include a change to the registry in your commit to -reflect the newly used value. - -It is current TSC policy to bump major version when ABI changes. If you -see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. -Commits may need to be reverted or a major version bump may need to happen. - ### 4. Update the changelog #### 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 upcoming release. `npm` maintains a list of [supported versions](https://github.com/npm/cli/blob/latest/lib/utils/unsupported.js#L3) that will need updating to include the new major release. +### Update `NODE_MODULE_VERSION` + +This macro in `src/node_version.h` is used to signal an ABI version for native +addons. It currently has two common uses in the community: + +* Determining what API to work against for compiling native addons, e.g. + [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for + much of what it wraps. +* Determining the ABI for downloading pre-built binaries of native addons, e.g. + [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as + exposed via `process.versions.modules` to help determine the appropriate + binary to download at install-time. + +The general rule is to bump this version when there are _breaking ABI_ changes +and also if there are non-trivial API changes. The rules are not yet strictly +defined, so if in doubt, please confer with someone that will have a more +informed perspective, such as a member of the NAN team. + +A registry of currently used `NODE_MODULE_VERSION` values is maintained at +. +When bumping `NODE_MODULE_VERSION`, you should choose a new value not listed +in the registry. Also include a change to the registry in your commit to +reflect the newly used value. Ensure that the release commit removes the +`-pre` suffix for the major version being prepared. + +It is current TSC policy to bump major version when ABI changes. If you +see a need to bump `NODE_MODULE_VERSION` outside of a majore release then +you should consult the TSC. Commits may need to be reverted or a major +version bump may need to happen. + ### Test releases and release candidates Test builds should be generated from the `vN.x-proposal` branch starting at