Release the Apache SkyWalking Node.js Agent

This guide explains how to release the Node.js Agent and how to check a release candidate. The shell scripts scripts/release.sh and scripts/release-finalize.sh update versions, create tags, sign files, stage files in SVN, create the GitHub release, and publish to npm. This guide covers the GPG key, vote, and announcement steps around those scripts.

master contains the current development version, such as 0.9.0-dev. Do not edit package.json by hand. scripts/release.sh removes -dev for the release commit and changes the branch to the next -dev version in the same pull request.

Publish the development documentation

The Next documentation should be registered in apache/skywalking-website as soon as this docs structure is merged. Do not wait for the next agent release. In the NodeJS Agent entry in data/docs.yml, set repoUrl to this repository and add the link /docs/skywalking-nodejs/next/readme/. The website build then imports docs/README.md and docs/menu.yml.

The release scripts

The release uses these three commands. The next sections explain each one.

bash scripts/release.sh --dry-run     # rehearse: full local build + sign + verify, NO push/svn/PR
bash scripts/release.sh               # cut the RC: tag, sign, svn-stage, open the release PR, print the [VOTE] email
# ... [VOTE] on dev@skywalking.apache.org for >= 72h, >= 3 binding +1 ...
bash scripts/release-finalize.sh      # promote svn dev -> release, publish the GitHub release, optional npm publish

You can also use npm run release and npm run release:finalize. With npm, use npm run release -- --dry-run for the dry run.

Both scripts ask y/N before each remote change. Run them on one trusted, single-user host because they read your SVN password. These settings are optional:

Variable / flag Effect Default
--dry-run or SW_RELEASE_DRY_RUN=1 Run locally with no remote changes: no push, SVN upload, or pull request off
SW_RELEASE_REPO_URL Git repo to clone + push https://github.com/apache/skywalking-nodejs.git
SW_RELEASE_BRANCH Branch to cut from master
SW_RELEASE_GH_REPO owner/repo for the release PR / GitHub release apache/skywalking-nodejs
SW_GPG_KEY Pin the signing key (release.sh sets this from your @apache.org key automatically) git/gpg default
NPM_OTP npm one-time password for the release-finalize.sh publish prompt

Before a real release, run unset SW_RELEASE_REPO_URL SW_RELEASE_BRANCH SW_RELEASE_GH_REPO. This removes test settings that could send release changes to the wrong repository.

Prerequisites (one-time)

  • Apache GPG key with an @apache.org user ID, added to the SkyWalking KEYS file:
    1. Upload the public key to a public key server.
    2. Register the fingerprint at id.apache.org.
    3. Append (never overwrite) your key to the SkyWalking KEYS file — PMC only; ask a PMC member if needed.
  • Tools: Node >= 20, plus git, svn, gh, gpg, shasum, tar (and license-eye, optional). Run gh auth login; for the npm publish, npm login as a maintainer of skywalking-backend-js.
  • Milestones: close the current milestone and create the next one in skywalking-nodejs and skywalking.

1. Cut the release candidate — bash scripts/release.sh

bash scripts/release.sh --dry-run     # rehearse first: full local build + sign + verify, NO push/svn/PR
bash scripts/release.sh               # the real cut

scripts/release.sh performs these steps. It asks for approval before each remote change.

  1. Check the GPG signer, required tools, and Node.js version.
  2. Clone master with submodules and create a prepare-release-<v> branch.
  3. Remove -dev, commit the release version, and tag the release commit.
  4. Build, sign, and check skywalking-nodejs-src-<v>.tgz{,.asc,.sha512}.
  5. Push the tag only after the checks pass. Add the next -dev commit and open the release pull request.
  6. Upload the release candidate to dist/dev/skywalking/node-js/<v>/.
  7. Print the [VOTE] email with the tag, commit, and SHA-512 value.

Release notes come from the auto-generated GitHub Release notes (CHANGELOG.md is a stub). Draft them once the tag exists: gh release create v<v> --draft --generate-notes --verify-tag --notes-start-tag v<prev>

2. Call for vote — dev@skywalking.apache.org

Send the [VOTE] email printed by the script. The template is below. Keep the vote open for at least 72 hours. It passes with at least three binding +1 votes from PMC members and more +1 votes than -1 votes.

Subject: [VOTE] Release Apache SkyWalking NodeJS version $VERSION

Hi the SkyWalking Community:
This is a call for vote to release Apache SkyWalking NodeJS version $VERSION.

Release notes:

 * https://github.com/apache/skywalking-nodejs/releases/tag/v$VERSION

Release Candidate:

 * https://dist.apache.org/repos/dist/dev/skywalking/node-js/$VERSION
 * sha512 checksums
   - sha512xxxxyyyzzz skywalking-nodejs-src-x.x.x.tgz

Release Tag :

 * (Git Tag) v$VERSION

Release Commit Hash :

 * https://github.com/apache/skywalking-nodejs/tree/<Git Commit Hash>

Keys to verify the Release Candidate :

 * https://dist.apache.org/repos/dist/release/skywalking/KEYS

Guide to build the release from source :

 * docs/en/contribution/build-and-test.md (in the source package)

Voting will start now and will remain open for at least 72 hours.
A release passes with at least 3 binding +1 (PMC) votes and more +1 than -1.

[ ] +1 Release this package.
[ ] +0 No opinion.
[ ] -1 Do not release this package because....

Thanks.

[1] docs/en/contribution/release.md, "Vote check" section (in the source package)

Vote check

Before voting +1, check the following items:

  1. Test the release features.
  2. Check that every file in the staging directory has .asc and .sha512 files. Do not use .md5.
  3. The source package skywalking-nodejs-src-$VERSION.tgz is in https://dist.apache.org/repos/dist/dev/skywalking/node-js/$VERSION with its .asc + .sha512.
  4. LICENSE and NOTICE are present in the source package.
  5. shasum -c skywalking-nodejs-src-$VERSION.tgz.sha512.
  6. gpg --verify skywalking-nodejs-src-$VERSION.tgz.asc skywalking-nodejs-src-$VERSION.tgz.
  7. Build from the source package following the build and test guide.
  8. Run the license header check with apache/skywalking-eyes, as configured in .github/workflows/license.yaml, and run npm run lint.

Close the vote

After the vote passes, send the result email. List the binding and non-binding voters.

[RESULT][VOTE] Release Apache SkyWalking NodeJS version $VERSION

72+ hours passed, we’ve got ($NUMBER) +1 bindings (and ... +1 non-bindings):

(list names)
+1 bindings:
xxx
...

+1 non-bindings:
xxx
...

Thank you for voting, I’ll continue the release process.

3. Finalize — bash scripts/release-finalize.sh

npm login                  # only if you will publish to npm (maintainer of skywalking-backend-js)
bash scripts/release-finalize.sh

The script checks npm access first and asks for approval before each remote change. It then:

  1. Moves the release candidate in SVN from dev/<v> to release/<v> and archives the older release.
  2. Publishes the GitHub release for v<v> and attaches the approved files.
  3. Optionally publishes skywalking-backend-js@<v> to npm. It skips this when the version is already published.

Then complete these steps:

  1. Merge the release pull request opened in step 1. master returns to the next -dev version, while the v<v> tag stays on the release commit.
  2. Update the website in apache/skywalking-website. Update the NodeJS Agent entries in data/releases.yml and data/docs.yml. Add the released documentation version and its commit. The one-time Next registration described above should already be present.
  3. [ANNOUNCE] email from your @apache.org address to dev@skywalking.apache.org and announce@apache.org:
Subject: [ANNOUNCEMENT] Apache SkyWalking NodeJS $VERSION Released

Hi the SkyWalking Community

On behalf of the SkyWalking Team, I’m glad to announce that Apache SkyWalking NodeJS $VERSION is now released.

SkyWalking NodeJS is the Node.js Agent for Apache SkyWalking. It reports distributed traces and Node.js runtime metrics.

Apache SkyWalking is an application performance monitoring system for distributed services.

Download Links: https://skywalking.apache.org/downloads/

Release Notes : https://github.com/apache/skywalking-nodejs/releases/tag/v$VERSION

Website: https://skywalking.apache.org/

SkyWalking NodeJS Resources:
- Issue: https://github.com/apache/skywalking/issues
- Mailing list: dev@skywalking.apache.org
- Documents: https://github.com/apache/skywalking-nodejs/blob/v$VERSION/docs/README.md

The Apache SkyWalking Team

Manual fallback

The scripts follow the standard ASF release steps. Read scripts/release.sh and scripts/release-finalize.sh before running any step by hand. Clone with --recurse-submodules, remove -dev with npm version <v> --no-git-tag-version, and run npm install. Commit and tag locally. Run npm run release-src, then check the source file, signature, and checksum before pushing the tag. Stage the three files in dist/dev/.../node-js/<v>/. After the vote, move the SVN directory from dev to release, publish the GitHub release, and run npm run build && npm publish.