Skip to content

Update Release guide #39544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
richardlau merged 4 commits into from
Jul 29, 2021
Merged

Update Release guide #39544

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
96cd561
doc: update backport labels in release guide
richardlau Jul 27, 2021
a5bc5f7
doc: fence command examples in release guide
richardlau Jul 27, 2021
7fa032b
doc: remove outdated ARM information from release guide
richardlau Jul 27, 2021
4350262
doc: move `NODE_MODULE_VERSION` in release guide
richardlau Jul 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
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>
  • Loading branch information
@richardlau
richardlau committed Jul 29, 2021
commit 43502622f53345fe1845bec1743d249484a288a6
58 changes: 30 additions & 28 deletions doc/guides/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://github.com/nodejs/node/blob/HEAD/doc/abi_version_registry.json>.
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
Expand Down Expand Up @@ -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
<https://github.com/nodejs/node/blob/HEAD/doc/abi_version_registry.json>.
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
Expand Down