Skip to content
Browse files

doc: update release guide with notes for major releases

Co-Authored-By: jasnell <>
Co-Authored-By: Rich Trott <>
Co-Authored-By: Beth Griggs <>

PR-URL: #25497
Reviewed-By: Beth Griggs <>
Reviewed-By: Rich Trott <>
Reviewed-By: Anna Henningsen <>
  • Loading branch information...
jasnell authored and BethGriggs committed Jan 14, 2019
1 parent cdebd32 commit 7b350bb3d45483a4b242de37b87448c5b79143b9
Showing with 94 additions and 0 deletions.
  1. +94 −0 doc/
@@ -32,6 +32,7 @@ official release builds for Node.js, hosted on <>.
* [17. Cleanup](#17-cleanup)
* [18. Announce](#18-announce)
* [19. Celebrate](#19-celebrate)
* [Major Releases](#major-Releases)

## Who can make a release?

@@ -663,6 +664,99 @@ Ping the IRC ops and the other [Partner Communities] liaisons.

_In whatever form you do this..._

## Major Releases

The process for cutting a new Node.js major release has a number of differences
from cutting a minor or patch release.

### Schedule

New Node.js Major releases happen twice per year:

* Even-numbered releases are cut in April.
* Odd-numbered releases are cut in October.

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.

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

Approximately three 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 `master` branch. Up until one month before the release
date, these must be kept in sync with `master` and must not be considered to
be stable branches (e.g. they may be force pushed).

The `vN.x` and `vN.x-staging` branches must be kept in sync with one another
up until the date of release.

One month or less before the release date, commits must be cherry-picked into
the two branches. To land `SEMVER-MAJOR` at this time requires no objections
from the TSC.

### Release Proposal

A draft release proposal should be created two months 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

### 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

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

#### 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
`CHANGELOG_V*.md` files.

The navigation headers in all of the `CHANGELOG_V*.md` files must be
updated to account for the new `CHANGELOG_V{N}.md` file.

Once the file is created, the root `` file must be updated to
reference the newly-created major release `CHANGELOG_V{N}.md`.

#### 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,
we compare the `v12.x` branch against the up to date `v11.x` branch). Make sure
that the local copy of the downlevel branch is up to date.

The commits in the generated changelog must then be organized:

* Remove all release commits from the list
* Remove all reverted commits and their reverts
* Separate all SEMVER-MAJOR, SEMVER-MINOR, and SEMVER-PATCH commits into lists

#### 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.

[CI lockdown procedure]:
[Build issue tracker]:
[ release-post.js script]:

0 comments on commit 7b350bb

Please sign in to comment.
You can’t perform that action at this time.