You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/06/24 08:51:39 UTC
(skywalking-nodejs) branch master updated: docs: fix build instructions (Node 20 + submodule) and make the release guide script-oriented (#136)
This is an automated email from the ASF dual-hosted git repository.
wu-sheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking-nodejs.git
The following commit(s) were added to refs/heads/master by this push:
new 4c340ac docs: fix build instructions (Node 20 + submodule) and make the release guide script-oriented (#136)
4c340ac is described below
commit 4c340ac8db5954a2c907bbcb44e8d06a19577ba4
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Wed Jun 24 16:51:34 2026 +0800
docs: fix build instructions (Node 20 + submodule) and make the release guide script-oriented (#136)
---
CONTRIBUTING.md | 26 ++++--
README.md | 2 +-
docs/How-to-release.md | 244 ++++++++++++++++++++++++++-----------------------
3 files changed, 148 insertions(+), 124 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 46b6dd7..e651767 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,21 +1,31 @@
# Compiling and Building
-We use NodeJS 14 to build skywalking-nodejs project, if you don't have NodeJS 14 installed,
-you can choose a node version manager like [nvm](https://github.com/nvm-sh/nvm) to easily
-manage multiple node vesions, or you can start a Docker container and build this project inside
-the container.
+We build skywalking-nodejs with NodeJS 20 (the current LTS baseline; CI tests Node 20, 22, and 24).
+If you don't have a suitable NodeJS installed, use a version manager such as
+[nvm](https://github.com/nvm-sh/nvm) to manage multiple node versions, or build inside a Docker
+container:
```shell
# Suppose you have the source codes in folder skywalking-nodejs
-docker run -it --rm -v $(pwd)/skywalking-nodejs:/workspace -w /workspace node:14 bash
+docker run -it --rm -v $(pwd)/skywalking-nodejs:/workspace -w /workspace node:20 bash
```
-Then run the following commands to build the project:
+The gRPC / protobuf definitions live in the `protocol/` git submodule, so initialize it first (or
+clone the repository with `--recurse-submodules`). Then install dependencies — the `prepare` hook
+generates the protobuf stubs into `src/proto/` — and compile:
```shell
+git submodule update --init --recursive
npm install
npm run build
```
-Warnings can be ignored, but if you have any error that prevents you to continue, try
-`rm -rf node_modules/` and then rerun the commands above.
+`npm run build` compiles the TypeScript sources into `lib/`. Other useful commands:
+
+```shell
+npm run lint # ESLint: code style + Apache license headers
+npm run test # plugin tests (require Docker)
+```
+
+Warnings can be ignored, but if an error prevents you from continuing, try `rm -rf node_modules/`
+and rerun the commands above.
diff --git a/README.md b/README.md
index b08dd18..2a31b3e 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ $ npm install --save skywalking-backend-js
## Set up NodeJS Agent
-SkyWalking NodeJS SDK requires SkyWalking backend (OAP) 8.0+ and NodeJS >= 14,
+SkyWalking NodeJS SDK requires SkyWalking backend (OAP) 8.0+ and NodeJS >= 20,
other versions are not tested and SkyWalking NodeJS SDK may or may not work,
please make sure to use the supported versions before reporting any issue.
diff --git a/docs/How-to-release.md b/docs/How-to-release.md
index c0d85ba..240fce2 100644
--- a/docs/How-to-release.md
+++ b/docs/How-to-release.md
@@ -1,84 +1,91 @@
# Apache SkyWalking NodeJS Release Guide
-This documentation guides the release manager to release the SkyWalking NodeJS in the Apache Way, and also helps people to check the release for voting.
+This guide releases SkyWalking NodeJS the Apache Way using the two release scripts, and helps
+voters check a release. The shell scripts [`scripts/release.sh`](../scripts/release.sh) and
+[`scripts/release-finalize.sh`](../scripts/release-finalize.sh) do the mechanical work (versioning,
+tagging, signing, svn staging, the GitHub release, npm); this guide covers the human steps around
+them (GPG/KEYS, the vote, the announce).
-## Automated release (recommended)
+`master` carries the in-flight dev version (e.g. `0.9.0-dev`), like SkyWalking's `-SNAPSHOT`. You
+do **not** edit `package.json` by hand — `scripts/release.sh` strips `-dev` for the release commit
+and bumps the branch back to the next `-dev` in the same PR.
-`master` carries the in-flight dev version (e.g. `0.9.0-dev`), like SkyWalking's `-SNAPSHOT` convention. Two scripts automate the rest. Run them on a single-user trusted host, with your Apache GPG key (an `@apache.org` uid, already in the [KEYS](https://dist.apache.org/repos/dist/release/skywalking/KEYS) file) configured and Node >= 20:
+## The release scripts
+
+The whole flow is three commands (steps 1–3 below detail each phase):
```shell
-npm run release # cut a release branch: strip -dev, commit + tag the release commit,
- # build + sign the source release, verify it, push the tag, add a
- # second commit bumping the branch to the next -dev, open the release PR,
- # upload the RC to svn dev, and print the [VOTE] email
-# ... after the vote passes (open >= 72h, >= 3 binding +1, more +1 than -1) ...
-npm run release:finalize # svn move dev -> release, publish the GitHub release, optionally publish to npm
-# then merge the release PR opened by `npm run release` (master returns to -dev; the tag stays put).
+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 do **not** bump the version by hand — `npm run release` strips the `-dev` suffix for the release commit and bumps the branch to the next dev version in the same PR (master returns to `-dev` when the PR merges).
-
-To rehearse the whole flow with **zero side effects** — a full local clone, strip, build, sign and verify, but **no** tag/branch push, **no** svn upload and **no** PR — run `npm run release -- --dry-run` (or `SW_RELEASE_DRY_RUN=1 npm run release`).
-
-If you intend to publish to npm in `release:finalize`, run `npm login` first (you must be a maintainer of `skywalking-backend-js`). The script verifies npm auth **up front** — before the irreversible svn move — and auto-skips the npm step if that version is already published.
-
-The rest of this guide is the reference those scripts implement, and the fallback for running a step by hand.
-
-## Prerequisites
+(They are also wired as `npm run release` / `npm run release:finalize` if you prefer npm — but note
+the dry-run flag then needs `npm run release -- --dry-run`.)
-1. Close (if finished, or move to next milestone otherwise) all issues in the current milestone from [skywalking-nodejs](https://github.com/apache/skywalking-nodejs/milestones) and [skywalking](https://github.com/apache/skywalking/milestones), create a new milestone for the next release.
-1. The version is managed by `npm run release` (it strips `-dev` for the release commit and bumps `master` to the next `-dev`); you do not edit `package.json` by hand. CHANGELOG.md is a stub — release notes are the auto-generated [GitHub Release](https://github.com/apache/skywalking-nodejs/releases) notes.
+Both scripts are **interactive** (every irreversible step asks `y/N`), must run on a single trusted
+host (they read your SVN password), and are heavily commented — read the two files above for the
+details. Knobs (all optional):
+| Variable / flag | Effect | Default |
+| :--- | :--- | :--- |
+| `--dry-run` or `SW_RELEASE_DRY_RUN=1` | Run everything locally, perform **no** remote mutation (no tag/branch push, no svn, no PR) | 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 |
-## Add your GPG public key to Apache svn
+> Tip: `unset SW_RELEASE_REPO_URL SW_RELEASE_BRANCH SW_RELEASE_GH_REPO` before a real release —
+> a stray override from an earlier test would otherwise retarget the clone/push.
-1. Upload your GPG public key to a public GPG site, such as [MIT's site](http://pgp.mit.edu:11371/).
+## Prerequisites (one-time)
-1. Log in [id.apache.org](https://id.apache.org/) and submit your key fingerprint.
+- **Apache GPG key** with an `@apache.org` uid, added to the SkyWalking `KEYS` file:
+ 1. Upload the public key to a keyserver (e.g. [MIT](http://pgp.mit.edu:11371/)).
+ 1. Register the fingerprint at [id.apache.org](https://id.apache.org/).
+ 1. **Append** (never overwrite) your key to the [SkyWalking KEYS](https://dist.apache.org/repos/dist/release/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/roll the milestone on
+ [skywalking-nodejs](https://github.com/apache/skywalking-nodejs/milestones) and
+ [skywalking](https://github.com/apache/skywalking/milestones), and create the next one.
-1. Add your GPG public key into [SkyWalking GPG KEYS](https://dist.apache.org/repos/dist/release/skywalking/KEYS) file, **you can do this only if you are a PMC member**. You can ask a PMC member for help. **DO NOT override the existed `KEYS` file content, only append your key at the end of the file.**
+Run the scripts on a single-user trusted host (they read your SVN password).
-
-## Build and sign the source code package
-
-`npm run release` automates this. To do it by hand, mirror the script — strip `-dev`, build, and push the tag **only after** the build verifies (master carries `$VERSION-dev`):
+## 1. Cut the release candidate — `bash scripts/release.sh`
```shell
-export VERSION=<the release version, e.g. 0.9.0> # bare semver
-
-git clone --recurse-submodules git@github.com:apache/skywalking-nodejs && cd skywalking-nodejs
-git checkout -b "prepare-release-$VERSION"
-npm version "$VERSION" --no-git-tag-version # strip -dev: package.json + lockfile -> $VERSION
-npm install
-git commit -am "Prepare release $VERSION"
-git tag -a "v$VERSION" -m "Release Apache SkyWalking-NodeJS $VERSION" # tag LOCALLY first
-
-npm run release-src # skywalking-nodejs-src-$VERSION.tgz{,.asc,.sha512}
-# verify the tarball + signature, THEN push the tag (and branch, for the next-dev PR):
-git push origin "v$VERSION" "prepare-release-$VERSION"
+bash scripts/release.sh --dry-run # rehearse first: full local build + sign + verify, NO push/svn/PR
+bash scripts/release.sh # the real cut
```
-## Upload to Apache svn
+`scripts/release.sh` does, each irreversible step behind a `y/N`:
-```bash
-svn co https://dist.apache.org/repos/dist/dev/skywalking/node-js/ release/skywalking/node-js
-mkdir -p release/skywalking/node-js/"$VERSION"
-cp skywalking-node-js/skywalking*.tgz release/skywalking/node-js/"$VERSION"
-cp skywalking-node-js/skywalking*.tgz.asc release/skywalking/node-js/"$VERSION"
-cp skywalking-node-js/skywalking*.tgz.sha512 release/skywalking/node-js/"$VERSION"
+1. preflight — the GPG signer is an `@apache.org` key, required tools present, Node >= 20;
+1. fresh recursive clone of `master`; cut a `prepare-release-<v>` branch; strip `-dev` and
+ commit + **tag** the release commit;
+1. build + sign + verify `skywalking-nodejs-src-<v>.tgz{,.asc,.sha512}`;
+1. push the tag (**only after** verify), add a `Prepare next release <next>-dev` commit, and
+ **open the release PR**;
+1. upload the RC to `dist/dev/skywalking/node-js/<v>/`;
+1. print the **[VOTE] email** (with the real tag, commit, and sha512 — copy it for step 2).
-cd release/skywalking && svn add node-js/$VERSION && svn commit node-js -m "Draft Apache SkyWalking-NodeJS release $VERSION"
-```
+> Release notes come from the auto-generated [GitHub Release](https://github.com/apache/skywalking-nodejs/releases)
+> 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>`
-## Call for vote in dev@ mailing list
+## 2. Call for vote — `dev@skywalking.apache.org`
-Call for vote in `dev@skywalking.apache.org`.
+Send the `[VOTE]` email the script printed (template below). Keep it open **>= 72 hours**; it
+passes with **>= 3 binding +1** (PMC) and more +1 than -1.
```text
Subject: [VOTE] Release Apache SkyWalking NodeJS version $VERSION
-Content:
-
Hi the SkyWalking Community:
This is a call for vote to release Apache SkyWalking NodeJS version $VERSION.
@@ -106,9 +113,10 @@ Keys to verify the Release Candidate :
Guide to build the release from source :
- * https://github.com/apache/skywalking-nodejs/blob/master/CONTRIBUTING.md#compiling-and-building
+ * https://github.com/apache/skywalking-nodejs/blob/v$VERSION/CONTRIBUTING.md#compiling-and-building
-Voting will start now and will remain open for at least 72 hours, all PMC members are required to give their votes.
+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.
@@ -119,92 +127,98 @@ Thanks.
[1] https://github.com/apache/skywalking-nodejs/blob/master/docs/How-to-release.md#vote-check
```
-## Vote Check
+### Vote check
-All PMC members and committers should check these before voting +1:
+Before voting +1, verify (all PMC members and committers):
1. Features test.
-1. All artifacts in staging repository are published with `.asc` and `.sha512` files.
-1. Source codes and distribution packages (`skywalking-nodejs-src-$VERSION.tgz`)
-are in `https://dist.apache.org/repos/dist/dev/skywalking/node-js/$VERSION` with `.asc`, `.sha512`.
-1. `LICENSE` and `NOTICE` are in source codes and distribution package.
-1. Check `shasum -c skywalking-nodejs-src-$VERSION.tgz.sha512`.
-1. Check `gpg --verify skywalking-nodejs-src-$VERSION.tgz.asc skywalking-nodejs-src-$VERSION.tgz`.
-1. Build distribution from source code package by following this [the build guide](#build-and-sign-the-source-code-package).
-1. License-header check via license-eye (`apache/skywalking-eyes`, as run by `.github/workflows/license.yaml`); style lint via `npm run lint`.
-
-Vote result should follow these:
+1. All artifacts in the staging dir are published with `.asc` and `.sha512` files (no `.md5`).
+1. 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`.
+1. `LICENSE` and `NOTICE` are present in the source package.
+1. `shasum -c skywalking-nodejs-src-$VERSION.tgz.sha512`.
+1. `gpg --verify skywalking-nodejs-src-$VERSION.tgz.asc skywalking-nodejs-src-$VERSION.tgz`.
+1. Build from the source package following the
+ [build guide](../CONTRIBUTING.md#compiling-and-building).
+1. License-header check via license-eye (`apache/skywalking-eyes`, as run by
+ `.github/workflows/license.yaml`); style lint via `npm run lint`.
-1. PMC vote is +1 binding, all others is +1 no binding.
+### Close the vote
-1. Within 72 hours, you get at least 3 (+1 binding), and have more +1 than -1. Vote pass.
+After it passes, send the closing mail, listing the binding and non-binding voters:
-1. **Send the closing vote mail to announce the result**. When count the binding and no binding votes, please list the names of voters. An example like this:
-
- ```
- [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.
- ```
+```text
+[RESULT][VOTE] Release Apache SkyWalking NodeJS version $VERSION
-## Publish release
+72+ hours passed, we’ve got ($NUMBER) +1 bindings (and ... +1 non-bindings):
-1. Move source codes tar balls and distributions to `https://dist.apache.org/repos/dist/release/skywalking/`, **you can do this only if you are a PMC member**.
+(list names)
++1 bindings:
+xxx
+...
- ```shell
- svn mv https://dist.apache.org/repos/dist/dev/skywalking/node-js/"$VERSION" https://dist.apache.org/repos/dist/release/skywalking/node-js/"$VERSION"
- ```
++1 non-bindings:
+xxx
+...
-1. Refer to the previous [PR](https://github.com/apache/skywalking-website/pull/190), update news and links on the website. There are several files need to modify.
+Thank you for voting, I’ll continue the release process.
+```
-1. Update [Github release page](https://github.com/apache/skywalking-nodejs/releases), follow the previous convention.
+## 3. Finalize — `bash scripts/release-finalize.sh`
-1. Publish to npmjs.com, this is optional for Apache releases, but we usually want to do this to let users use it conveniently.
+```shell
+npm login # only if you will publish to npm (maintainer of skywalking-backend-js)
+bash scripts/release-finalize.sh
+```
- ```shell
- npm run build && npm pack && npm publish
- ```
+It does, each irreversible step behind a `y/N` (npm auth is verified **up front**):
-**NOTE**: please double check before publishing to npmjs.com, it's difficult to unpublish and republish the module at the moment.
+1. promotes the RC on svn: `dev/<v>` -> `release/<v>`, retiring the previous (strictly-older)
+ release (it auto-archives to archive.apache.org);
+1. publishes the **GitHub release** on `v<v>` (auto-notes), attaching the voted artifacts;
+1. optionally publishes `skywalking-backend-js@<v>` to npm (skipped if already published).
-1. Send ANNOUNCE email to `dev@skywalking.apache.org` and `announce@apache.org`, the sender should use his/her Apache email account.
+Then finish the human steps it reminds you about:
- ```
- Subject: [ANNOUNCEMENT] Apache SkyWalking NodeJS $VERSION Released
+1. **Merge the release PR** opened in step 1 (`master` returns to the next `-dev`; the `v<v>` tag
+ stays pinned to the release commit).
+1. **Website** ([apache/skywalking-website](https://github.com/apache/skywalking-website)): add the
+ release event, bump the NodeJS Agent block in `data/releases.yml` and the docs pointer in
+ `data/docs.yml` (see a prior [PR](https://github.com/apache/skywalking-website/pull/190)).
+1. **[ANNOUNCE] email** from your `@apache.org` address to `dev@skywalking.apache.org` and
+ `announce@apache.org`:
- Content:
+```text
+Subject: [ANNOUNCEMENT] Apache SkyWalking NodeJS $VERSION Released
- Hi the SkyWalking Community
+Hi the SkyWalking Community
- On behalf of the SkyWalking Team, I’m glad to announce that SkyWalking NodeJS $VERSION is now released.
+On behalf of the SkyWalking Team, I’m glad to announce that SkyWalking NodeJS $VERSION is now released.
- SkyWalking NodeJS: The NodeJS Agent for Apache SkyWalking, which provides the native tracing abilities for NodeJS backend project.
+SkyWalking NodeJS: The NodeJS Agent for Apache SkyWalking, which provides the native tracing abilities for NodeJS backend project.
- SkyWalking: APM (application performance monitor) tool for distributed systems, especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.
+SkyWalking: APM (application performance monitor) tool for distributed systems, especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.
- Download Links: http://skywalking.apache.org/downloads/
+Download Links: http://skywalking.apache.org/downloads/
- Release Notes : https://github.com/apache/skywalking-nodejs/releases/tag/v$VERSION
+Release Notes : https://github.com/apache/skywalking-nodejs/releases/tag/v$VERSION
- Website: http://skywalking.apache.org/
+Website: http://skywalking.apache.org/
- SkyWalking NodeJS Resources:
+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/README.md
+- Mailing list: dev@skywalking.apache.org
+- Documents: https://github.com/apache/skywalking-nodejs/blob/v$VERSION/README.md
- The Apache SkyWalking Team
+The Apache SkyWalking Team
```
+## Manual fallback
+The scripts implement the standard ASF steps and are heavily commented; if you must run a step by
+hand, read [`scripts/release.sh`](../scripts/release.sh) and
+[`scripts/release-finalize.sh`](../scripts/release-finalize.sh). The essentials: clone with
+`--recurse-submodules`; `npm version <v> --no-git-tag-version` to strip `-dev`; `npm install`;
+commit; tag locally; `npm run release-src` to build + sign; verify the tarball + signature;
+**then** push the tag; `svn` the three artifacts to `dist/dev/.../node-js/<v>/`; after the vote
+`svn mv` dev -> release; publish the GitHub release; `npm run build && npm publish`.