From b180b71495726204af2815615c8959fc57e54801 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 14 Jan 2019 09:04:16 -0800 Subject: [PATCH 1/9] meta: update release guide with notes for major releases --- doc/releases.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/doc/releases.md b/doc/releases.md index 38332809303bde..818c2cc7c24237 100644 --- 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 From 114470fc23630da6b3ea444937bedcd52c711b13 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Tue, 29 Jan 2019 15:29:47 -0800 Subject: [PATCH 2/9] [Squash] nit Co-Authored-By: jasnell --- doc/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/releases.md b/doc/releases.md index 818c2cc7c24237..6ed8409bc088bf 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -675,7 +675,7 @@ 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. +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). From 2c27bacfeb130c38d41c43e0ff384d5baa82173e Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Tue, 29 Jan 2019 15:30:08 -0800 Subject: [PATCH 3/9] [Squash] nit Co-Authored-By: jasnell --- doc/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/releases.md b/doc/releases.md index 6ed8409bc088bf..d236fe58a9d31e 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -686,7 +686,7 @@ announced immediately following the release of 12.0.0). ### Release Branch -Approximately three months before the a major release, new `vN.x` and +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 From bcc73bccd6ff983d03cc9c0e0a126d7f7010b25e Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Tue, 29 Jan 2019 15:30:22 -0800 Subject: [PATCH 4/9] [Squash] nit Co-Authored-By: jasnell --- doc/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/releases.md b/doc/releases.md index d236fe58a9d31e..f5e348ffb37782 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -733,7 +733,7 @@ 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`. +reference the newly created major release `CHANGELOG_V{N}.md`. #### Generate the changelog From 27941f5df0f25e67d61fef2803f5d4caf6ca0b2d Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Tue, 29 Jan 2019 15:30:33 -0800 Subject: [PATCH 5/9] [Squash] nit Co-Authored-By: jasnell --- doc/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/releases.md b/doc/releases.md index f5e348ffb37782..33e38ca8f0ee85 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -753,7 +753,7 @@ The commits in the generated changelog must then be organized: 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. +judgment there. [CI lockdown procedure]: https://github.com/nodejs/build/blob/master/doc/jenkins-guide.md#restricting-access-for-security-releases From 784a7650c5bda5e9b7194d9e50e3e6933bd20192 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 26 Jun 2019 07:48:42 -0700 Subject: [PATCH 6/9] [Squash] nits Co-Authored-By: Rich Trott --- doc/releases.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/releases.md b/doc/releases.md index 33e38ca8f0ee85..56cc9477433064 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -672,15 +672,15 @@ from cutting a minor or patch release. New Node.js Major releases happen twice per year: -* Even Numbered Releases are cut in April -* Odd Numbered Releases are cut in October +* 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. +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). +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 +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). @@ -689,13 +689,13 @@ announced immediately following the release of 12.0.0). 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 +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 +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 +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. @@ -704,7 +704,7 @@ from the TSC. 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). +changelog). ### Test Releases and Release Candidates @@ -718,7 +718,7 @@ per week. Always run test releases and release candidates through the Canary in the Goldmine tool for additional testing. -### Change Logs +### Changelogs Generating major release changelogs is a bit more involved than minor and patch changelogs. @@ -733,7 +733,7 @@ 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 `CHANGELOG_V{N}.md`. +reference the newly-created major release `CHANGELOG_V{N}.md`. #### Generate the changelog From 271301dc5b1fad6310e17bff42f78694e7f06607 Mon Sep 17 00:00:00 2001 From: Beth Griggs Date: Fri, 6 Sep 2019 11:25:50 +0100 Subject: [PATCH 7/9] fixup: add to table of contents --- doc/releases.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/releases.md b/doc/releases.md index 56cc9477433064..a4b05b3dbc8e68 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,7 +664,7 @@ Ping the IRC ops and the other [Partner Communities] liaisons. _In whatever form you do this..._ -## Differences for Major Releases +## Major Releases The process for cutting a new Node.js major release has a number of differences from cutting a minor or patch release. From fec2d025110320875274218e16122c0f132c93d6 Mon Sep 17 00:00:00 2001 From: Beth Griggs Date: Fri, 6 Sep 2019 14:50:40 +0100 Subject: [PATCH 8/9] fixup: fix long line --- doc/releases.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/releases.md b/doc/releases.md index a4b05b3dbc8e68..a76b966e1d8a62 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -678,8 +678,8 @@ New Node.js Major releases happen twice per year: 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. +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 From ad003502893991ccbfa9445d4dffc8f30a1ab2ea Mon Sep 17 00:00:00 2001 From: Beth Griggs Date: Fri, 6 Sep 2019 17:00:45 +0100 Subject: [PATCH 9/9] fixup: remote 'note that' --- doc/releases.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/releases.md b/doc/releases.md index a76b966e1d8a62..38f0b8b4f08ba5 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -730,7 +730,7 @@ 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 +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