Node.js release guide
In order to go through the whole release process, you will first need to do some required setup on your local machine.
Each release is signed by the person doing the release. You will need to have a signing key that can be publicly verified to do a release of Node.js. If you don't have a key yet, one easy way to get a new one is to use https://keybase.io.
In addition to signing keys, you will need SSH keys to get access to a remote shell nodejs.org. Simply generate a pair of SSH keys and paste your public key in an issue in github.com/nodejs/LTS to mention that you need to be able to access nodejs.org to do Node.js releases.
Currently, the release process is made for a setup where the nodejs/node and joyent/node-website repositories sit side by side.
So you'll need to have both projects checked out in locations similar to:
~/foo/bar/node/v0.12
~/foo/bar/node/node-website
where /foo/bar is a common prefix.
Add the signing key ID (see "Signing keys" to know how to get a signing key) to Git's config to be able to sign tags by adding the following content to your ~/.gitconfig file:
[user]
email = [email protected]
name = Your Name
signingkey = SIGNING_KEY_ID
where SIGNING_KEY_ID is the identifier of your signing key. Mine for
instance is 0246406D.
In ~/.ssh/config, make sure that the following entry is present:
Host nodejs.org
User node
git checkout -b v$(python tools/getnodeversion.py)-release
(git log --first-parent --graph --pretty=format:'%h%d %s (%an)' v$(head -n1 ChangeLog | awk '{ print $3 }')^..HEAD | sort -k 3 ; echo ""; echo ""; cat ChangeLog ) > ChangeLog.x; mv ChangeLog.x ChangeLog
vi ChangeLog
At that point, modify ChangeLog to keep only entries for api changes and bug
fixes for the public api. All documentation changes, build fixes or anything
that has no impact on end users must not be included in the ChangeLog.
The exception is for dependency upgrades: they are moved to the top of the ChangeLog, and they don't include the author's name.
Also, make sure to add the sha1 for the commit that was used to create the previous release.
It's now time to update the AUTHORS file:
./node tools/update-authors.js
and then make sure that new authors have been properly added (by using git diff for instance).
Run the following command to turn your local code base into an official release:
perl -pi -e 's/define NODE_VERSION_IS_RELEASE 0/define NODE_VERSION_IS_RELEASE 1/' src/node_version.h
git commit -am "$(bash tools/changelog-head.sh)"
After running this command, review the commit message with git show and make sure that it's properly formatted
and the content is correct.
git push [email protected]:GITHUB_USERNAME/node.git v$(python tools/getnodeversion.py)-release
and replace GITHUB_USERNAME by your GitHub username.
The OSX binary package cannot be built automatically from the CI platform because at some point the binary and package signature processes will need to display a prompt to confirm the usage of the signature key and to ask for a passphrase, and there's an issue that makes the build process stalls when that happens on our OSX Jenkins agent.
You will need to install manta to be able to download the keys and certificates used to sign the OSX application and package.
mget -O /NodeCore/stor/joyent-dev-int.p12
mget -O /NodeCore/stor/joyent-dev-app.p12
Once downloaded, you will need to add these certificates and keys to your keychain. Simply double-click on these files and follow instructions.
INT_SIGN='Developer ID Installer: Joyent, Inc (X4ETB2T5LK)' APP_SIGN='Developer ID Application: Joyent, Inc (X4ETB2T5LK)'
You will first need to install the PackageMaker OSX application, then run:
PACKAGEMAKER=/Applications/PackageMaker.app/Contents/MacOS/PackageMaker INT_SIGN="Developer ID Installer: Joyent, Inc (X4ETB2T5LK)" APP_SIGN="Developer ID Application: Joyent, Inc (X4ETB2T5LK)" make pkg -j 6
Upload the OSX pkg first before kicking off the nodejs-release job from Jenkins so that it's accounted for when generating the checksums file:
scp out/node-v$(python tools/getnodeversion.py).pkg [email protected]:archive/node/tmp/v$(python tools/getnodeversion.py)
Go to http://jenkins.nodejs.org/job/nodejs-release/ and click on "Build with parameters". Fill in the build parameters with the following values:
-
GIT_BRANCHshould be the result of runningecho v$(python tools/getnodeversion.py)-release. -
GIT_REPOshould be your own fork of nodejs/node. -
INT_SIGNmust be filled withDeveloper ID Installer: Joyent, Inc (X4ETB2T5LK). Omitting to fill this field will make the release process do a nightly release. -
APP_SIGNmust be filled withDeveloper ID Application: Joyent, Inc (X4ETB2T5LK).
When running the nodejs-release job on Jenkins, connect to the windows box
(node-build.cloudapp.net:50708, see the Node.js CI administration guide for
more information) to authorize the signing, otherwise it stalls the whole
process.
The current build process generates unneeded .pdb, .lib and .exe files when doing a v0.12.x release.
To avoid distributing these files, make sure that you remove them from /home/staging when the nodejs-release Jenkins jobs has completed:
$ ssh [email protected]
$ cd node/tmp/archive/v0.12.x
$ rm icu* genrb* genccode*
$ cd x64 && rm icu* genrb* genccode*
Sometimes, SHASUMS* files are not generated, but they are needed for the next step of the release process. Go to /home/staging and edit shasums.sh to point to the proper directory where new release's files are located (e.g /home/staging/v0.12.6). Then run sh /home/staging/shasums.sh, all SHASUMS* files should now be present.
Point your browser to https://nodejs.org/dist/staging/ and download newly created release files. Smoke test them by doing the following for releases on all supported platforms:
- Install node.
- Run `node -p 'process.versions' and make sure that all version numbers are correct (especially dependencies if they've been upgraded with this release).
- Install a module with binary add-ons as dependencies (like
wswithnpm install ws) to make sure that node-gyp, npm and node works correctly. Clean up ~/.node-gyp and runnpm cache cleanbefore doing so to force a fresh download/build.
It's now time to move the release files from nodejs.org/dist/staging/ to nodejs.org/dist/ so that it is published as an official release and can be downloaded from the website or version managers like nvm.
Simply run:
./tools/node-release-post-build.sh -u GITHUB_USERNAME
It is now time to push the release branch, tag and merge commit of the release branch to the parent branch upstream (nodejs/node):
git push [email protected]:nodejs/node.git v$(python tools/getnodeversion.py) v$(python tools/getnodeversion.py)-release v$(python tools/getnodeversion.py | sed -E 's#\.[0-9]+$##')
API docs of the newly released version need to be published to the website. Go to the node repository (not node-website) and run:
make website-upload
At that point in time, there should be a file with the .md extension in your node-website local clone.
Edit it and add any information you think would help users of Node.js understand better what this new release is about. Most of the time, the generated file is fine. In case of releases that fix security vulnerabilities, you will need to add some background around what these issues are and how they were fixed by Node.js.
Once the blog post is ready, run make test-blog and check that the blog post displays correctly.
Now go in the node-website directory and do:
make release
This will publish the blog post and changes to the Downloads section of the website.
Finally, commit and push changes to the website to the master branch.
