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 <[email protected]>
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 [email protected] 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 [email protected]: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 — `[email protected]`
-Call for vote in `[email protected]`.
+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 `[email protected]` and
`[email protected]`, 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
`[email protected]` and
+ `[email protected]`:
- 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: [email protected]
- - Documents:
https://github.com/apache/skywalking-nodejs/blob/v$VERSION/README.md
+- Mailing list: [email protected]
+- 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`.
