The Life and Times of a Node.js Release
Danielle Adams
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
The Life and Times of a Node.js Release
What is a release?
A release in Node.js refers to the code changes that have been made to the code base that will be built and released on the Node.js distribution channels. Code changes are evaluated by commit.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Node.js may have up to 5 active release lines at a time. A release line is the semver major (ie. v18.x, etc) version that is maintained.
Releasers prepare the releases and are responsible for testing the release builds and deploying the releases.
Stages of a Release
Current
The first 6 months of a release are the commits from the base branch. Everything lands that is not a semver major change.
1
2
Active LTS
For the next 12 months, commits that have "baked" for 2 weeks from the Current release are pulled into the next Active release.
3
Maintenance LTS
For the next 18 months, Maintenance releases only get bug fixes that target that release and security patches.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
0
Release the prepared major release
3 B.R.
Branch off the nodejs/node base branch to begin preparing major release
18 A.R.
Release is moved to Maintenance mode
6 A.R.
Release is moved to Active LTS and receives a code name
36 A.R.
Release reaches
End-of-Life
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Odd semver major releases are also deprecated
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Number of Commits by Release
How can you maintain multiple releases at once?
Release lines have two git branches that are used to work off of. One branch represents the state of what is released, and the other is the branch used to prepare the following release.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Node.js collaborators use GitHub labels to categorize commits by their semver change so it is easier to figure out which commits should go into a release line.
v14.0.0
v16.0.0
v18.0.0
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
main
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
main
v18.x
v18.x-staging
// get the diff SHAs
node git:(v18.x-staging) branch-diff main v18.x --exclude-labels=semver-major,[...]
b6d62f7fad
a2fcb6c51b
4a8b8d5767
Pulling in Commits
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
// cherry pick the available commits
node git:(v18.x-staging) git cherry-pick b6d62f7fad
How do you pull in multiple commits per release?
There may be hundreds of commits in a single release, so automation is key. While we can't automate all the cherry-picks (yet) because a human needs to resolve conflicts, scripts are used to move commits around and drop any conflicting changes.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
What is a backport?
A backport is a change that has already been made and approved on the main branch, but the change lands on a release line branch with substantial conflicts. Therefore, a backport is created where the change is based off the release line's staging branch.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
node git:(v18.x-staging) branch-diff main v18.x --exclude-labels=semver-major,[...]
| xargs git cherry-pick
Pulling in Commits
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
node git:(v18.x-staging) make test
Divide and Conquer
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
eac0e59bc2
2615d7653c
d6c2316452
865a5784fd
6b9253a81a
70047b0c34
29c35ea823
e236af8d54
bf0c312893
2a4452a53a
ce59abceb4
dc96633638
43e2f60be0
8f16a8c98f
e5c807e115
aa7167ff3b
0ee6643d36
HEAD
Last commit from last release
$ git bisect start
$ git bisect bad eac0e59bc2
$ git bisect good 0ee6643d36
git bisect started on bf0c312893
node git:(v18.x-staging) branch-diff main v18.x --exclude-labels=semver-major,[...] | xargs git cherry-pick
node git:(v18.x-staging) make test
Pulling in Commits
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
node git:(v18.x-staging) git bisect start
node git:(v18.x-staging) git bisect good
node git:(v18.x-staging) git bisect bad
Bisecting: 8 revisions left to test after this (roughly 4 steps)
node git:(v18.x-staging) make test
node git:(v18.x-staging) git bisect good
8f16a8c98f is the first bad commit
8f16a8c98f is the first bad commit
Pulling in Commits
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
node git:(v18.x-staging) git rebase -i
node git:(v18.x-staging) make test
Preparing the release
- Write the release notes
- Propose the release on GitHub
- Run the CI tests
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
node git:(v14.x-staging) changelog-maker --markdown --start-ref v14.20.1
* **deps**: update corepack to 0.14.1 (Node.js GitHub Bot) [#44704]
* **deps**: update corepack to 0.14.0 (Node.js GitHub Bot) [#44509]
* **deps**: update corepack to 0.13.0 (Node.js GitHub Bot) [#44318]
* **deps**: update corepack to 0.12.3 (Node.js GitHub Bot) [#44229]
* **deps**: update corepack to 0.12.2 (Node.js GitHub Bot) [#44159]
* **deps**: update corepack to 0.12.1 (Node.js GitHub Bot) [#43965]
* **deps**: update corepack to 0.12.0 (Node.js GitHub Bot) [#43748]
How do security patches work on a public code base?
The Node.js project has a private code base that is kept in sync with the public repository. Security patches are made to the base branch and each release line, and the code is reviewed and tested before a release is started and the vulnerability is made public.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Building the release
- Create the release builds
- Tag the release on GitHub
- Promote and sign the release
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Now that I've released, what's next?
Releasers start preparing for the next releases. Releases and major release lines are scheduled years and months in advance. There are Node releases currently scheduled through 2026.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Code names (Fermium, Gallium, etc) have been chosen years in advance. Right now, there are not code names for "Q" and "W", so if you have ideas please open a pull request!
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
# of Releases per Release Line Today
Does this really benefit Node.js developers?
This model allows Node.js to have multiple release lines for multiple types of developers and platforms at once.
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
While some developers may want the latest features that have been merged to the Node.js codebase, others can only sustain an update every few years.
Want to learn more?
- Release Guides:
github.com/nodejs/node/blob/main/doc/contributing/releases.md - Release Working Group:
github.com/nodejs/release
Danielle Adams, The Life and Times of a Node.js Release
@adamzdanielle
Thank you!
Danielle Adams
tweets @adamzdanielle
code @danielleadams
The Life and Times of a Node.js Release
By Danielle Adams
The Life and Times of a Node.js Release
The Node.js release schedule may seem overwhelming to keep up with, maintaining 3 or 4 versions at a time, but there’s no shortage of effort that goes into releases to support the wide use of JavaScript across the web. Many Node.js contributors spend hours discussing APIs, running tests, and preparing release notes for a single release - but how does it all come together? As a releaser, I will discuss the work that goes into a release, tips I’ve picked up along the way, and how every contribution counts. Learn how the Node.js project manages semver major releases, security patches, long-term support, and everything in between.
- 838