Skip to content

Commit c95e9ca

Browse files
jasnelltargos
jasnell
authored and
targos
committed
doc: update release guide with notes for major releases
Co-Authored-By: jasnell <[email protected]> Co-Authored-By: Rich Trott <[email protected]> Co-Authored-By: Beth Griggs <[email protected]> PR-URL: #25497 Reviewed-By: Beth Griggs <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>
1 parent b9c082d commit c95e9ca

File tree

1 file changed

+94
-0
lines changed

1 file changed

+94
-0
lines changed

‎doc/releases.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)