meta: update release guide with notes for major releases

jasnell · Jan 14, 2019 · Jan 29, 2019 · Jan 29, 2019 · Jan 29, 2019 · Jan 29, 2019
commit b180b71495726204af2815615c8959fc57e54801
diff --git a/doc/releases.md b/doc/releases.md
@@ -663,6 +663,99 @@ Ping the IRC ops and the other [Partner Communities] liaisons.
 
 _In whatever form you do this..._
 
+## Differences for 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 (e.g. 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 the 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 in to
+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
+change log).
+
+### 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.
+
+### Change Logs
+
+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.
+
+Note that 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 `CHANLGELOV_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
+judgement 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