diff --git a/doc/releases.md b/doc/releases.md index 38332809303bde..38f0b8b4f08ba5 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -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 +changelog). + +### 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 +changelogs. + +#### 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 `CHANGELOG.md` 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]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases [Build issue tracker]: https://github.com/nodejs/build/issues/new [nodejs.org release-post.js script]: https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js