@@ -32,6 +32,7 @@ official release builds for Node.js, hosted on <https://nodejs.org/>.
3232 * [ 17. Cleanup] ( #17-cleanup )
3333 * [ 18. Announce] ( #18-announce )
3434 * [ 19. Celebrate] ( #19-celebrate )
35+ * [ Major Releases] ( #major-Releases )
3536
3637## Who can make a release?
3738
@@ -663,6 +664,99 @@ Ping the IRC ops and the other [Partner Communities] liaisons.
663664
664665_ In whatever form you do this..._
665666
667+ ## Major Releases
668+
669+ The process for cutting a new Node.js major release has a number of differences
670+ from cutting a minor or patch release.
671+
672+ ### Schedule
673+
674+ New Node.js Major releases happen twice per year:
675+
676+ * Even-numbered releases are cut in April.
677+ * Odd-numbered releases are cut in October.
678+
679+ Major releases should be targeted for the third Tuesday of the release month.
680+
681+ A major release must not slip beyond the release month. In other words, major
682+ releases must not slip into May or November.
683+
684+ The release date for the next major release should be announced immediately
685+ following the current release (e.g. the release date for 13.0.0 should be
686+ announced immediately following the release of 12.0.0).
687+
688+ ### Release Branch
689+
690+ Approximately three months before a major release, new ` vN.x ` and
691+ ` vN.x-staging ` branches (where ` N ` indicates the major release) should be
692+ created as forks of the ` master ` branch. Up until one month before the release
693+ date, these must be kept in sync with ` master ` and must not be considered to
694+ be stable branches (e.g. they may be force pushed).
695+
696+ The ` vN.x ` and ` vN.x-staging ` branches must be kept in sync with one another
697+ up until the date of release.
698+
699+ One month or less before the release date, commits must be cherry-picked into
700+ the two branches. To land ` SEMVER-MAJOR ` at this time requires no objections
701+ from the TSC.
702+
703+ ### Release Proposal
704+
705+ A draft release proposal should be created two months before the release. A
706+ separate ` vN.x-proposal ` branch should be created that tracks the ` vN.x `
707+ branch. This branch will contain the draft release commit (with the draft
708+ changelog).
709+
710+ ### Test Releases and Release Candidates
711+
712+ Test builds should be generated from the ` vN.x-proposal ` branch starting at
713+ about 6 weeks before the release.
714+
715+ Release Candidates should be generated from the ` vN.x-proposal ` branch starting
716+ at about 4 weeks before the release, with a target of one release candidate
717+ per week.
718+
719+ Always run test releases and release candidates through the Canary in the
720+ Goldmine tool for additional testing.
721+
722+ ### Changelogs
723+
724+ Generating major release changelogs is a bit more involved than minor and patch
725+ changelogs.
726+
727+ #### Create the changelog file
728+
729+ In the ` doc/changelogs ` directory, create a new ` CHANGELOG_V{N}.md ` file where
730+ ` {N} ` is the major version of the release. Follow the structure of the existing
731+ ` CHANGELOG_V*.md ` files.
732+
733+ The navigation headers in all of the ` CHANGELOG_V*.md ` files must be
734+ updated to account for the new ` CHANGELOG_V{N}.md ` file.
735+
736+ Once the file is created, the root ` CHANGELOG.md ` file must be updated to
737+ reference the newly-created major release ` CHANGELOG_V{N}.md ` .
738+
739+ #### Generate the changelog
740+
741+ To generate a proper major release changelog, use the ` branch-diff ` tool to
742+ compare the ` vN.x ` branch against the ` vN-1.x ` branch (e.g. for Node.js 12.0,
743+ we compare the ` v12.x ` branch against the up to date ` v11.x ` branch). Make sure
744+ that the local copy of the downlevel branch is up to date.
745+
746+ The commits in the generated changelog must then be organized:
747+
748+ * Remove all release commits from the list
749+ * Remove all reverted commits and their reverts
750+ * Separate all SEMVER-MAJOR, SEMVER-MINOR, and SEMVER-PATCH commits into lists
751+
752+ #### Generate the notable changes
753+
754+ For a major release, all SEMVER-MAJOR commits that are not strictly internal,
755+ test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR
756+ commits may be listed as notable changes on a case-by-case basis. Use your
757+ judgment there.
758+
759+
666760[ CI lockdown procedure ] : https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases
667761[ Build issue tracker ] : https://github.com/nodejs/build/issues/new
668762[ nodejs.org release-post.js script ] : https://github.com/nodejs/nodejs.org/blob/master/scripts/release-post.js
0 commit comments