1 # Node.js release process
3 This document describes the technical aspects of the Node.js release process.
5 Technical Steering Committee (TSC) to create, promote, and sign
6 official release builds for Node.js, hosted on <https://nodejs.org/>.
10 * [Who can make a release?](#who-can-make-a-release)
11   * [1. Jenkins release access](#1-jenkins-release-access)
12   * [2. <nodejs.org> access](#2-nodejsorg-access)
13   * [3. A publicly listed GPG key](#3-a-publicly-listed-gpg-key)
14 * [How to create a release](#how-to-create-a-release)
15   * [0. Pre-release steps](#0-pre-release-steps)
16   * [1. Update the staging branch](#1-update-the-staging-branch)
17   * [2. Create a new branch for the release](#2-create-a-new-branch-for-the-release)
18   * [3. Update `src/node_version.h`](#3-update-srcnode_versionh)
19   * [4. Update the changelog](#4-update-the-changelog)
20   * [5. Create release commit](#5-create-release-commit)
21   * [6. Propose release on GitHub](#6-propose-release-on-github)
22   * [7. Ensure that the release branch is stable](#7-ensure-that-the-release-branch-is-stable)
23   * [8. Produce a nightly build _(optional)_](#8-produce-a-nightly-build-optional)
24   * [9. Produce release builds](#9-produce-release-builds)
25   * [10. Test the build](#10-test-the-build)
26   * [11. Tag and sign the release commit](#11-tag-and-sign-the-release-commit)
27   * [12. Set up for the next release](#12-set-up-for-the-next-release)
28   * [13. Cherry-pick the release commit to `master`](#13-cherry-pick-the-release-commit-to-master)
29   * [14. Push the release tag](#14-push-the-release-tag)
30   * [15. Promote and sign the release builds](#15-promote-and-sign-the-release-builds)
31   * [16. Check the release](#16-check-the-release)
32   * [17. Create a blog post](#17-create-a-blog-post)
33   * [18. Create the release on GitHub](#18-create-the-release-on-github)
34   * [19. Cleanup](#19-cleanup)
35   * [20. Announce](#20-announce)
36   * [21. Celebrate](#21-celebrate)
37 * [LTS releases](#lts-releases)
38 * [Major releases](#major-releases)
40 ## Who can make a release?
42 Release authorization is given by the Node.js TSC. Once authorized, an
45 ### 1. Jenkins release access  argument
47 There are three relevant Jenkins jobs that should be used for a release flow:
50 **[node-test-pull-request](https://ci.nodejs.org/job/node-test-pull-request/)**
51 is used for a final full-test run to ensure that the current *HEAD* is stable.
54 **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** can be used
55 to create a nightly release for the current *HEAD* if public test releases are
59 **c.** **Release builds:**
60 **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** does all of
61 the work to build all required release assets. Promotion of the release files is
71 <https://nodejs.org/download/release/>.
73 The Jenkins release build workers upload their artifacts to the web server as
80 Release builds require manual promotion by an individual with SSH access to the
85 ### 3. A publicly-listed GPG key
89 responsible for that release. In order to be able to verify downloaded binaries,
91 signed by someone who has been authorized to create a release.
93 The GPG keys should be fetchable from a known third-party keyserver. The SKS
94 Keyservers at <https://sks-keyservers.net> are recommended. Use the
96 do an ASCII-armored export of your key first:
99 $ gpg --armor --export email@server.com > ~/nodekey.asc
105 $ gpg --keyserver pool.sks-keyservers.net --recv-keys <FINGERPRINT>
110 Additionally, full GPG key fingerprints for individuals authorized to release
113 ## How to create a release
117 * Dates listed below as _"YYYY-MM-DD"_ should be the date of the release **as
118   UTC**. Use `date -u +'%Y-%m-%d'` to find out what this is.
120   the release version.
121 * Examples will use the fictional release version `1.2.3`.
123 ### 0. Pre-release steps
125 Before preparing a Node.js release, the Build Working Group must be notified at
126 least one business day in advance of the expected release. Coordinating with
127 Build is essential to make sure that the CI works, release files are published,
128 and the release blog post is available on the project website.
133 When preparing a security release, contact Build at least two weekdays in
134 advance of the expected release. To ensure that the security patch(es) can be
135 properly tested, run a `node-test-pull-request` job against the `master` branch
136 of the `nodejs-private/node-private` repository a day or so before the
146 $ git checkout v1.x-staging
147 $ git reset --hard upstream/v1.x-staging
153 … label](https://github.com/nodejs/node/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Av8.x).
163 When landing the PR add the `Backport-PR-URL:` line to each commit. Close the
165 `backport-requested-vN.x` to `backported-to-vN.x`.
168 [`branch-diff`](https://github.com/nodejs/branch-diff). The tool is available on
170 metadata, as well as the GitHub labels such as `semver-minor` and
171 `semver-major`. One drawback is that when the `PR-URL` metadata is accidentally
175 For a list of commits that could be landed in a patch release on v1.x:
178 …-diff v1.x-staging master --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-req…
182 cherry-picked.
186 * Checking for errors (incorrect `PR-URL`)
187 * Checking semver status - Commits labeled as `semver-minor` or `semver-major`
188 should only be cherry-picked when appropriate for the type of release being
191 `baking-for-lts` tag.
193 When you are ready to cherry-pick commits, you can automate with the following
194 command. (For semver-minor releases, make sure to remove the `semver-minor` tag
195 from `exclude-label`.)
198 …-diff v1.x-staging master --exclude-label=semver-major,semver-minor,dont-land-on-v1.x,backport-req…
201 When cherry-picking commits, if there are simple conflicts you can resolve
202 them. Otherwise, add the `backport-requested-vN.x` label to the original PR
204 backport PR. You can refer the owner of the PR to the "[Backporting to Release
205  Lines](https://github.com/nodejs/node/blob/HEAD/doc/guides/backporting-to-release-lines.md)" guide.
207 If commits were cherry-picked in this step, check that the test still pass.
213 Then, push to the staging branch to keep it up-to-date.
216 $ git push upstream v1.x-staging
219 ### 2. Create a new branch for the release  argument
221 Create a new branch named `vx.y.z-proposal`, off the corresponding staging
225 $ git checkout -b v1.2.3-proposal upstream/v1.x-staging
230 Set the version for the proposed release using the following macros, which are
240 be produced with a version string that does not have a trailing pre-release tag:
250 Collect a formatted list of commits since the last release. Use
251 [`changelog-maker`](https://github.com/nodejs/changelog-maker) to do this:
254 $ changelog-maker --group
257 `changelog-maker` counts commits since the last tag and if the last tag
259 `--start-ref` argument:
262 $ changelog-maker --group --filter-release --start-ref v1.2.2
265 `--filter-release` will remove the release commit from the previous release.
269 There is a separate `CHANGELOG_Vx.md` file for each major Node.js release line.
272 in the release branch (e.g. a release for Node.js v4 would be added to the
281 ## YYYY-MM-DD, Version x.y.z (Release Type), @releaser
292 * Include the full list of commits since the last release here. Do not include "Working on X.Y.Z+1"…
295 The release type should be either Current, LTS, or Maintenance, depending on the
296 type of release being produced.
298 You can use `branch-diff` to get a list of commits with the `notable-change`
302 $ branch-diff upstream/v1.x v1.2.3-proposal --require-label=notable-change -format=simple
309 releases in each major release line. A link to the new release needs to be added
310 to it. Follow the existing examples and be sure to add the release to the *top*
311 of the list. The most recent release for each release line is shown in **bold**
313 accordingly by removing the bold styling from the previous release.
317 If this release includes new APIs then it is necessary to document that they
326 sed -i "s/REPLACEME/$VERSION/g" doc/api/*.md` or `perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md
331 If this release includes any new deprecations it is necessary to ensure that
335 occur when the PR is landed, but a check will be made when the release build is
338 ### 5. Create release commit  argument
342 release. When committing these to git, use the following message format:
345 YYYY-MM-DD, Version x.y.z (Release Type)
349 * Copy the notable changes list here, reformatted for plain-text
353 `This is a security release.` to allow the
354 [distribution indexer](https://github.com/nodejs/nodejs-dist-indexer) to
358 YYYY-MM-DD, Version x.y.z (Release Type)
360 This is a security release.
364 * Copy the notable changes list here, reformatted for plain-text
367 ### 6. Propose release on GitHub  argument
369 Push the release branch to `nodejs/node`, not to your own fork. This allows
370 release branches to more easily be passed between members of the release team if
373 Create a pull request targeting the correct release line. For example, a
374 `v5.3.0-proposal` PR should target `v5.x`, not master. Paste the CHANGELOG
392 good place to @-mention the relevant contributors.
394 After opening the PR, update the release commit to include `PR-URL` metadata and
395 force-push the proposal.
397 ### 7. Ensure that the release branch is stable  argument
399 Run a **[`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/)**
401 release.
403 Also run a **[`node-test-commit-v8-linux`](https://ci.nodejs.org/job/node-test-commit-v8-linux/)**
404 test run if the release contains changes to `deps/v8`.
406 Perform some smoke-testing. There is the
407 **[`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/)** CI job for this
414 If there is a reason to produce a test release for the purpose of having others
416 **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** and wait for
424 ### 9. Produce release builds  argument
426 Use **[iojs+release](https://ci-release.nodejs.org/job/iojs+release/)** to
427 produce release artifacts. Enter the commit that you want to build from and
428 select "release" for "disttype".
435 All release workers should achieve "SUCCESS" (and be green, not red). A release
439 You can rebuild the release as many times as you need prior to promoting them if
457 ### 11. Tag and sign the release commit  argument
459 Once you have produced builds that you're happy with, create a new tag. By
460 waiting until this stage to create tags, you can discard a proposed release if
462 tag and pushed it to GitHub, you ***must not*** delete and re-tag. If you make
463 a mistake after tagging then you'll have to version-bump and start again and
467 -v v6.0.0`. The message should look something like `2016-04-26 Node.js v6.0.0
468 (Current) Release`.
470 Install `git-secure-tag` npm module:
473 $ npm install -g git-secure-tag
476 Create a tag using the following command:
479 $ git secure-tag <vx.y.z> <commit-sha> -sm "YYYY-MM-DD Node.js vx.y.z (<release-type>) Release"
482 `release-type` is either "Current" or "LTS". For LTS releases, you should also
483  include the release code name.
486 2019-10-22 Node.js v10.17.0 'Dubnium' (LTS) Release
492 ### 12. Set up for the next release  argument
494 On release proposal branch, edit `src/node_version.h` again and:
504 PR-URL: <full URL to your release proposal PR>
508 version number _and_ a pre-release tag.
510 Merge your release proposal branch into the stable branch that you are releasing
515 $ git merge --ff-only v1.2.3-proposal
517 $ git checkout v1.x-staging
519 $ git push upstream v1.x-staging
522 ### 13. Cherry-pick the release commit to `master`  argument
526 $ git cherry-pick v1.x^
533 $ git checkout --ours HEAD -- src/node_version.h
537 placeholders (that happens when a change previously landed on another release
541 Then finish cherry-picking and push the commit upstream:
545 $ git cherry-pick --continue
550 **Do not** cherry-pick the "Working on vx.y.z" commit to `master`.
552 ### 14. Push the release tag  argument
563 remainder of the release steps.
565 ### 15. Promote and sign the release builds  argument
567 **The same individual who signed the release tag must be the one
571 Use `tools/release.sh` to promote and sign the build. Before doing this, you'll
580 The key can be loaded either with `ssh-add`:
584 $ ssh-add ~/.ssh/node_id_rsa
591 $ ./tools/release.sh -i ~/.ssh/node_id_rsa
594 `tools/release.sh` will perform the following actions when run:
599 to: `gpg --list-secret-keys` to list your keys. If you don't have any keys, it
605 along with the list of artifacts. It will use the `dist-promotable` command on
606 the server to find these. You will be asked, for each promotable release,
607 whether you want to proceed. If there is more than one release to promote (there
608 shouldn't be), be sure to only promote the release you are responsible for.
611 release. The command on the server will be similar to: `dist-promote vx.y.z`.
612 After this step, the release artifacts will be available for download and a
613 `SHASUMS256.txt` file will be present. The release will still be unsigned,
620 --default-key YOURKEY --digest-algo SHA256 --clearsign /path/to/SHASUMS256.txt`.
625 similar to: `gpg --default-key YOURKEY --digest-algo SHA256 --detach-sign /path/to/SHASUMS256.txt`.
629 **g.** Upload the `SHASUMS256.txt` files back to the server into the release
633 **It is possible to only sign a release by running `./tools/release.sh -s
636 ### 16. Check the release  argument
638 Your release should be available at `https://nodejs.org/dist/vx.y.z/` and
642 at <https://nodejs.org/api/>. Check that the release catalog files are correct
645 ### 17. Create a blog post
649 release. However, the blog post is not yet fully automatic.
651 Create a new blog post by running the [nodejs.org release-post.js script][].
665 * Always use pull-requests on the [nodejs.org repository][]. Be respectful
666   of the website team, but you do not have to wait for PR sign-off. Please
670   Blog: vX.Y.Z release post
672   Refs: <full URL to your release proposal PR>
678 ### 18. Create the release on GitHub  argument
680 * Go to the [New release page](https://github.com/nodejs/node/releases/new).
682 * For release title, copy the title from the changelog.
684 * Click on the "Publish release" button.
688 Close your release proposal PR and delete the proposal branch.
696 > v5.8.0 of @nodejs is out: <https://nodejs.org/en/blog/release/v5.8.0/>
701 24 hour prior notice. If known, please include the date and time the release
713 ### Marking a release line as LTS
715 To mark a release line as LTS, the following changes must be made to
722 for the LTS release.
727 -#define NODE_MINOR_VERSION 12
728 -#define NODE_PATCH_VERSION 1
732 -#define NODE_VERSION_IS_LTS 0
733 -#define NODE_VERSION_LTS_CODENAME ""
737 -#define NODE_VERSION_IS_RELEASE 0
741 The changes must be made as part of a new semver-minor release.
743 ### Update release labels
745 The `lts-watch-vN.x` issue label must be created, with the same color as other
746 existing labels for that release line, such as `vN.x`.
748 If the release is transitioning from Active LTS to Maintenance, the
749 `backport-requested-vN.x` label must be deleted.
753 The process for cutting a new Node.js major release has a number of differences
754 from cutting a minor or patch release.
760 * Even-numbered releases are cut in April.
761 * Odd-numbered releases are cut in October.
763 Major releases should be targeted for the third Tuesday of the release month.
765 A major release must not slip beyond the release month. In other words, major
768 The release date for the next major release should be announced immediately
769 following the current release (e.g. the release date for 13.0.0 should be
770 announced immediately following the release of 12.0.0).
772 ### Release branch
774 Approximately three months before a major release, new `vN.x` and
775 `vN.x-staging` branches (where `N` indicates the major release) should be
776 created as forks of the `master` branch. Up until one month before the release
780 The `vN.x` and `vN.x-staging` branches must be kept in sync with one another
781 up until the date of release.
783 One month or less before the release date, commits must be cherry-picked into
784 the two branches. To land `SEMVER-MAJOR` at this time requires no objections
787 ### Create release labels
792 * `backport-blocked-vN.x`
793 * `backport-open-vN.x`
794 * `backport-requested-vN.x`
795 * `backported-to-vN.x`
796 * `dont-land-on-vN.x`
802 ### Release proposal
804 A draft release proposal should be created two months before the release. A
805 separate `vN.x-proposal` branch should be created that tracks the `vN.x`
806 branch. This branch will contain the draft release commit (with the draft
809 Notify the `@nodejs/npm` team in the release proposal PR to inform them of the
810 upcoming release. `npm` maintains a list of [supported versions](https://github.com/npm/cli/blob/la…
811 that will need updating to include the new major release.
819   [NAN](https://github.com/nodejs/nan) uses it to form a compatibility-layer for
821 * Determining the ABI for downloading pre-built binaries of native addons, e.g.
822   [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) uses this value as
824   binary to download at install-time.
827 and also if there are non-trivial API changes. The rules are not yet strictly
835 reflect the newly used value. Ensure that the release commit removes the
836 `-pre` suffix for the major version being prepared.
839 see a need to bump `NODE_MODULE_VERSION` outside of a majore release then
843 ### Test releases and release candidates
845 Test builds should be generated from the `vN.x-proposal` branch starting at
846 about 6 weeks before the release.
848 Release Candidates should be generated from the `vN.x-proposal` branch starting
849 at about 4 weeks before the release, with a target of one release candidate
852 Always run test releases and release candidates through the Canary in the
857 Generating major release changelogs is a bit more involved than minor and patch
860 #### Create the changelog file
862 In the `doc/changelogs` directory, create a new `CHANGELOG_V{N}.md` file where
863 `{N}` is the major version of the release. Follow the structure of the existing
870 reference the newly-created major release `CHANGELOG_V{N}.md`.
874 To generate a proper major release changelog, use the `branch-diff` tool to
875 compare the `vN.x` branch against the `vN-1.x` branch (e.g. for Node.js 12.0,
881 * Remove all release commits from the list
883 * Separate all SEMVER-MAJOR, SEMVER-MINOR, and SEMVER-PATCH commits into lists
887 For a major release, all SEMVER-MAJOR commits that are not strictly internal,
888 test, or doc-related are to be listed as notable changes. Some SEMVER-MINOR
889 commits may be listed as notable changes on a case-by-case basis. Use your
895 specified a release line ("track" in Snap terminology). This should be updated
902 …: https://github.com/nodejs/build/blob/HEAD/doc/jenkins-guide.md#restricting-access-for-security-r…
904 [Partner Communities]: https://github.com/nodejs/community-committee/blob/HEAD/governance/PARTNER_C…
906 [nodejs.org release-post.js script]: https://github.com/nodejs/nodejs.org/blob/HEAD/scripts/release…