Skip to content

meta: add support for alpha prerelease tag #63135

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

Open
aduh95 wants to merge 2 commits into
base: main
Choose a base branch
from
+94 −69
Open

meta: add support for alpha prerelease tag #63135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3eab912
meta: add support for alpha prerelease tag
aduh95 May 5, 2026
819b022
fixup! meta: add support for alpha prerelease tag
aduh95 Jul 2, 2026
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
2 changes: 1 addition & 1 deletion .github/workflows/major-release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: Major Release

on:
schedule:
- cron: 0 0 15 2,8 * # runs at midnight UTC every 15 February and 15 August
- cron: 0 0 15 2 * # runs at midnight UTC every 15 February

permissions:
contents: read
Expand Down
139 changes: 77 additions & 62 deletions doc/contributing/releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,11 @@ already defined in `src/node_version.h`:
#define NODE_MAJOR_VERSION x
#define NODE_MINOR_VERSION y
#define NODE_PATCH_VERSION z

// And for alpha releases:
#define NODE_ALPHA_MAJOR_VERSION a
#define NODE_ALPHA_MINOR_VERSION b
#define NODE_ALPHA_PATCH_VERSION c
Comment on lines +363 to +365

@RafaelGSS RafaelGSS May 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't include MINOR or PATCH for Alpha. Possibly, we should only have:

#define NODE_IS_ALPHA_RELEASE 0
#define NODE_ALPHA_MAJOR_VERSION 0

and increment NODE_ALPHA_MAJOR_VERSION on every release until LTS.

@aduh95 aduh95 May 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why? What would be the upside?

@RafaelGSS RafaelGSS May 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's simpler. We won't need to maintain a guarantee that v27.0.0-alpha.2 won't break v27.0.0-alpha.1 users, as it would need to be guaranteed if we decide to ship v27.0.0-alpha.1.1.0 on top of v27.0.0-alpha.1.0.0

@RafaelGSS RafaelGSS May 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that starting simpler would allow us to go to your suggested model if we feel the need. The opposite is not true.

@aduh95 aduh95 May 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The opposite is not true.

I don't think so, either we need to pick a system and stick to it, either we can change if we feel the need. I don't see why we could go from -alpha.1 to -alpha.1.0.1 and not from -alpha.1.0.1 to -alpha.2

@Renegade334 Renegade334 May 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we seek to provide semver semantics within the alpha phase, then we've just re-invented the old release model IMO. May need discussion, but I think it makes more sense to have the alpha versioning be linear, with no undertaking to provide any non-breakage guarantees between any two alpha builds. (I imagine that would make things significantly more straightforward for releasers as well!)

@trivikr trivikr May 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally prefer <prerelease>.<num> since it's shorter and widely adopted by ecosystem, including existing Node.js rc versions.
I'd posted examples in nodejs/Release#1154 (comment)

@aduh95 aduh95 May 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

then we've just re-invented the old release model IMO

Not at all, the key difference is that we plan on releasing semver-major changes during the alpha period – which we would not do with the old release model.
The blog post announcing the new schedule explicitly says "The Alpha channel fills the early-testing role that odd-numbered releases once served", so it's definitely a goal to stick to the old release schedule.

I imagine that would make things significantly more straightforward for releasers as well!

I don't really see why that would be the case, adding the semver-• label on PRs is not done by releasers – and we want to add those labels regardless how we name the prereleases.

no undertaking to provide any non-breakage guarantees between any two alpha builds

We make our own rules, we don't have to guarantee anything. The goal is to document (via the version number) when there are breakages, and when we think there are none.

@marco-ippolito marco-ippolito May 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On one side, we already know which commits are semver major, patch and minor so the versioning should not add too much complexity. On the other side you always increment by one regardless, so it's a bit easier. I would prefer the full semver since provides more information, and shouldnt add too much churn

@RafaelGSS RafaelGSS Jul 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please @nodejs/releasers chime in

```

Set the `NODE_VERSION_IS_RELEASE` macro value to `1`. This causes the build to
Expand All @@ -367,6 +372,14 @@ be produced with a version string that does not have a trailing pre-release tag:
#define NODE_VERSION_IS_RELEASE 1
```

<details>
<summary>Major version release</summary>

Remove the `NODE_ALPHA_MAJOR_VERSION`, `NODE_ALPHA_MINOR_VERSION`, and
`NODE_ALPHA_PATCH_VERSION` macros.

</details>

### 4. Update the changelog

#### Step 1: Collect the formatted list of changes
Expand Down Expand Up @@ -826,8 +839,8 @@ project README.

On release proposal branch, edit `src/node_version.h` again and:

* Increment `NODE_PATCH_VERSION` by one
* Change `NODE_VERSION_IS_RELEASE` back to `0`
* Increment `NODE_PATCH_VERSION` (or `NODE_ALPHA_PATCH_VERSION` for alpha releases) by one.
* Change `NODE_VERSION_IS_RELEASE` back to `0`.

Commit this change with the following commit message format:

Expand Down Expand Up @@ -894,9 +907,12 @@ git restore --source=upstream/main src/node_version.h
On the main branch, instead of reverting changes made to `src/node_version.h`
edit it instead and:

* Increment `NODE_MAJOR_VERSION` by one
* Reset `NODE_PATCH_VERSION` to `0`
* Change `NODE_VERSION_IS_RELEASE` back to `0`
* Increment `NODE_MAJOR_VERSION` by one.
* Reset `NODE_PATCH_VERSION` and `NODE_MINOR_VERSION` to `0`.
* Set `NODE_ALPHA_MAJOR_VERSION`, `NODE_ALPHA_MINOR_VERSION`, and
`NODE_ALPHA_PATCH_VERSION` back to `0` (`main` should already have this, the
release commit will have them removed).
* Change `NODE_VERSION_IS_RELEASE` back to `0`.

Amend the current commit to apply the changes:

Expand Down Expand Up @@ -1207,9 +1223,9 @@ git node release --prepare --startLTS
To mark a release line as LTS, the following changes must be made to
`src/node_version.h`:

* The `NODE_MINOR_VERSION` macro must be incremented by one
* The `NODE_PATCH_VERSION` macro must be set to `0`
* The `NODE_VERSION_IS_LTS` macro must be set to `1`
* The `NODE_MINOR_VERSION` macro must be incremented by one.
* The `NODE_PATCH_VERSION` macro must be set to `0`.
* The `NODE_VERSION_IS_LTS` macro must be set to `1`.
* The `NODE_VERSION_LTS_CODENAME` macro must be set to the code name selected
for the LTS release.

Expand Down Expand Up @@ -1278,15 +1294,15 @@ from cutting a minor or patch release.

### Schedule

New Node.js Major releases happen twice per year:
New Node.js Major releases happen once per year:

* Even-numbered releases are cut in April.
* Odd-numbered releases are cut in October.
* Branch-off is in October.
* Semver-major release is in April.

Major releases should be targeted for the third Tuesday of the release month.

A major release must not slip beyond the release month. In other words, major
releases must not slip into May or November.
releases must not slip into May.

The @nodejs/releasers make a call for releasers 3 months in advance.
Currently, this call is automated in the `#nodejs-release-private`
Expand All @@ -1296,26 +1312,25 @@ The release date for the next major release should be announced immediately
following the current release (e.g. the release date for 13.0.0 should be
announced immediately following the release of 12.0.0).

### Release branch
### Branch-off (October)

Approximately two months before a major release, new `vN.x` and
`vN.x-staging` branches (where `N` indicates the major release) should be
created as forks of the `main` branch. Up until the cut-off date announced by
the releaser, these must be kept in sync with `main`.
#### Release branch

The `vN.x` and `vN.x-staging` branches must be kept in sync with one another
up until the date of the release.
Approximately six months before a major release, new `vN.x` and
`vN.x-staging` branches (where `N` indicates the major release) should be
created as forks of the `main` branch. Alpha releases should be released picking
up commits from `main`. Target the first alpha release to be released the same
day as the previous release line is graduated to LTS status.

If a `SEMVER-MAJOR` pull request lands on the default branch within one month
prior to the major release date, it must not be included on the new major
staging branch, unless there is consensus from the Node.js releasers team to
do so. This measure aims to ensure better stability for the release candidate
(RC) phase, which begins approximately two weeks prior to the official release.
By restricting `SEMVER-MAJOR` commits in this period, we provide more time for
thorough testing and reduce the potential for major breakages, especially in
LTS lines.
thorough testing and reduce the potential for major breakages.

### Create release labels
#### Create release labels

The following issue labels must be created:

Expand All @@ -1330,31 +1345,17 @@ The label description can be copied from existing labels of previous releases.
The label color must be the same for all new labels, but different from the
labels of previous releases.

### Release proposal
#### Initial Alpha Release proposal

@targos targos Jul 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Initial Alpha Release proposal
#### Initial Alpha release proposal


A draft release proposal should be created 6 weeks before the release. A
A draft release proposal should be created before the release. A
separate `vN.x-proposal` branch should be created that tracks the `vN.x`
branch. This branch will contain the draft release commit (with the draft
changelog).

Notify the `@nodejs/npm` team in the release proposal PR to inform them of the
upcoming release.

To keep the branch in sync until the release date, it can be as simple as
doing the following:

> Make sure to check that there are no PRs with the label `dont-land-on-vX.x`.

```bash
git checkout vN.x
git reset --hard upstream/main
git checkout vN.x-staging
git reset --hard upstream/main
git push upstream vN.x
git push upstream vN.x-staging
```

### Update `NODE_MODULE_VERSION`
##### 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:
Expand Down Expand Up @@ -1384,24 +1385,12 @@ see a need to bump `NODE_MODULE_VERSION` outside of a major 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
about 6 weeks before the release.

Release Candidates should be generated from the `vN.x-proposal` branch starting
at about 4 weeks before the release, with a target of one release candidate
per week.

Always run test releases and release candidates through the Canary in the
Goldmine tool for additional testing.

### Changelogs
##### Changelogs

Generating major release changelogs is a bit more involved than minor and patch
changelogs.

#### Create the changelog file
###### Create the changelog file

In the `doc/changelogs` directory, create a new `CHANGELOG_V{N}.md` file where
`{N}` is the major version of the release. Follow the structure of the existing
Expand All @@ -1413,7 +1402,7 @@ updated to account for the new `CHANGELOG_V{N}.md` file.
Once the file is created, the root `CHANGELOG.md` file must be updated to
reference the newly-created major release `CHANGELOG_V{N}.md`.

#### Generate the changelog
###### Generate the changelog

To generate a proper major release changelog, use the `branch-diff` tool to
compare the `vN.x` branch against the `vN-1.x` branch (e.g. for Node.js 12.0,
Expand All @@ -1432,14 +1421,7 @@ $ branch-diff upstream/vN-1.x upstream/vN.x --require-label=semver-minor --group
$ branch-diff upstream/vN-1.x upstream/vN.x --exclude-label=semver-major,semver-minor --group --filter-release --markdown # get all patches
```

#### Generate the notable changes

For a major release, all SEMVER-MAJOR commits that are not strictly internal,
test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR
commits may be listed as notable changes on a case-by-case basis. Use your
judgment there.

### Update the expected assets
##### Update the expected assets

The promotion script does a basic check that the expected files are present.
Open a pull request in the Build repository to add the list of expected files
Expand All @@ -1448,6 +1430,39 @@ version of the release), in the [expected assets][] folder. The change will
need to be deployed onto the web server by a member of the [build-infra team][]
before the release is promoted.

### Semver-major release (April)

#### Release proposal

A draft release proposal should be created 6 weeks before the release. A
separate `vN.x-proposal` branch should be created that tracks the `vN.x`
branch. This branch will contain the draft release commit (with the draft
changelog).

Notify the `@nodejs/npm` team in the release proposal PR to inform them of the
upcoming release.

Major release proposal should contain a single commit, the release one. All
semver-major changes must have landed in a alpha version before the major is
released. Semver-major changes that have missed the alpha period will be included
in the next major release line.

##### Marking a release line as "out of Alpha"

To mark a release line as stable, the following changes must be made to
`src/node_version.h`:

* Remove `NODE_ALPHA_MAJOR_VERSION`, `NODE_ALPHA_MINOR_VERSION`, and
`NODE_ALPHA_PATCH_VERSION`.

#### Generate the notable changes

For a major release, all SEMVER-MAJOR commits that are not strictly internal,
test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR
commits may be listed as notable changes on a case-by-case basis. Use your
judgment there.
Include the notable changes from the Alpha versions where it applies.

### Snap

The Node.js [Snap][] package has a "default" for installs where the user hasn't
Expand Down
22 changes: 16 additions & 6 deletions src/node_version.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@

#define NODE_VERSION_IS_RELEASE 0

#define NODE_ALPHA_MAJOR_VERSION 0
#define NODE_ALPHA_MINOR_VERSION 0
#define NODE_ALPHA_PATCH_VERSION 0

#ifndef NODE_STRINGIFY
#define NODE_STRINGIFY(n) NODE_STRINGIFY_HELPER(n)
#define NODE_STRINGIFY_HELPER(n) #n
Expand All @@ -41,18 +45,24 @@
#endif

#ifndef NODE_TAG
# if NODE_VERSION_IS_RELEASE
# define NODE_TAG ""
# else
# define NODE_TAG "-pre"
# endif
#if NODE_VERSION_IS_RELEASE
#ifdef NODE_ALPHA_MAJOR_VERSION
#define NODE_TAG \
"-alpha." NODE_STRINGIFY(NODE_ALPHA_MAJOR_VERSION) "." NODE_STRINGIFY( \
NODE_ALPHA_MINOR_VERSION) "." NODE_STRINGIFY(NODE_ALPHA_PATCH_VERSION)
#else
#define NODE_TAG ""
#endif // NODE_ALPHA_MAJOR_VERSION
#else // NODE_VERSION_IS_RELEASE
#define NODE_TAG "-pre"
#endif // NODE_VERSION_IS_RELEASE
#else // NODE_TAG
// NODE_TAG is passed without quotes when rc.exe is run from msbuild
# define NODE_EXE_VERSION NODE_STRINGIFY(NODE_MAJOR_VERSION) "." \
NODE_STRINGIFY(NODE_MINOR_VERSION) "." \
NODE_STRINGIFY(NODE_PATCH_VERSION) \
NODE_STRINGIFY(NODE_TAG)
#endif
#endif // NODE_TAG

# define NODE_VERSION_STRING NODE_STRINGIFY(NODE_MAJOR_VERSION) "." \
NODE_STRINGIFY(NODE_MINOR_VERSION) "." \
Expand Down
Loading