From 5e0c519fd1d1b7fe7af54eb5d907bcf3bd246faf Mon Sep 17 00:00:00 2001 From: Manos Kalaitzoglou Date: Tue, 29 Sep 2026 09:48:21 +0300 Subject: [PATCH 1/2] ci: publish npm package on GitHub releases --- .github/workflows/npm-publish.yml | 95 +++++++++++++++++++++++++++++++ TypeScript/README.md | 44 ++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 .github/workflows/npm-publish.yml diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml new file mode 100644 index 0000000..80f0b1b --- /dev/null +++ b/.github/workflows/npm-publish.yml @@ -0,0 +1,95 @@ +name: Publish to npm + +on: + release: + types: [published] + +permissions: + contents: read + +concurrency: + group: npm-publish-${{ github.event.release.tag_name }} + cancel-in-progress: false + +jobs: + publish: + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + id-token: write + defaults: + run: + working-directory: TypeScript + + steps: + - name: Check out the release tag + uses: actions/checkout@v7 + with: + ref: refs/tags/${{ github.event.release.tag_name }} + persist-credentials: false + + - name: Set up Node.js + uses: actions/setup-node@v7 + with: + node-version: '24' + registry-url: https://registry.npmjs.org + package-manager-cache: false + + - name: Validate the release version + id: release + env: + RELEASE_TAG: ${{ github.event.release.tag_name }} + IS_PRERELEASE: ${{ github.event.release.prerelease }} + run: | + node --input-type=module <<'NODE' + import { appendFileSync, readFileSync } from 'node:fs'; + + const { version } = JSON.parse(readFileSync('package.json', 'utf8')); + const { RELEASE_TAG, IS_PRERELEASE, GITHUB_OUTPUT } = process.env; + if (RELEASE_TAG !== version && RELEASE_TAG !== `v${version}`) { + throw new Error(`Release tag ${RELEASE_TAG} must match package.json version ${version} (with an optional v prefix).`); + } + + const isPrereleaseVersion = version.split('+')[0].includes('-'); + if (IS_PRERELEASE === 'true' && !isPrereleaseVersion) { + throw new Error('GitHub prereleases must use a prerelease package version, such as 3.2.0-beta.1.'); + } + + const distTag = isPrereleaseVersion ? 'next' : 'latest'; + appendFileSync(GITHUB_OUTPUT, `dist-tag=${distTag}\n`); + console.log(`Publishing @arcweave/arcscript@${version} with npm tag ${distTag}.`); + NODE + + - name: Set up pnpm + uses: pnpm/action-setup@v6 + with: + package_json_file: TypeScript/package.json + + - name: Set up Java for ANTLR + uses: actions/setup-java@v6 + with: + distribution: temurin + java-version: '17' + + - name: Generate parsers + working-directory: . + run: sh generate.sh + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build package + run: pnpm run build + + - name: Run tests + run: pnpm test --run + + # Trusted publishing requires npm 11.5.1 or newer. + - name: Update npm + run: npm install --global npm@11 + + - name: Publish package + env: + NPM_DIST_TAG: ${{ steps.release.outputs.dist-tag }} + run: npm publish --access public --provenance --tag "$NPM_DIST_TAG" diff --git a/TypeScript/README.md b/TypeScript/README.md index 699071e..dfedc7d 100644 --- a/TypeScript/README.md +++ b/TypeScript/README.md @@ -278,6 +278,50 @@ pnpm lint The build writes compiled files and declarations to `dist/`. +## Publishing releases + +The [`Publish to npm` workflow](../.github/workflows/npm-publish.yml) publishes +`@arcweave/arcscript` when a GitHub release is published. It checks out the release +tag, generates the parsers, installs dependencies from the lockfile, builds the +package, and runs the tests before publishing with provenance. + +### One-time npm setup + +An npm package maintainer must add a GitHub Actions trusted publisher in the +[`@arcweave/arcscript` package settings](https://www.npmjs.com/package/@arcweave/arcscript/access): + +| Setting | Value | +| --- | --- | +| Organization or user | `arcweave` | +| Repository | `arcscript-interpreters` | +| Workflow filename | `npm-publish.yml` | +| Environment name | Leave empty | +| Allowed actions | Enable direct publishing with `npm publish` | + +The workflow uses npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) +through GitHub Actions OIDC. No `NPM_TOKEN` repository secret is needed. +Merge the workflow into `main` and configure the trusted publisher before making +the next release. + +### Making a release + +1. Update `version` in `TypeScript/package.json` and merge the change into `main`. + For example, run `pnpm version 3.2.0 --no-git-tag-version` from `TypeScript/`. +2. Create a GitHub release from that commit with a matching tag, such as `v3.2.0` + or `3.2.0`. Both tag formats are supported; a mismatch fails the workflow. +3. Publish the GitHub release. Stable versions are published to npm's `latest` tag. + Prerelease versions, such as `3.2.0-beta.1`, are published to `next` and can be + installed with `npm install @arcweave/arcscript@next`. GitHub prereleases must + use a prerelease package version. To release a stable version afterward, bump + to `3.2.0` and publish a new release with its own matching tag. +4. Check the `Publish to npm` run in the repository's Actions tab. + +Saving a draft release or pushing a tag alone does not publish to npm. Each +release needs a version that has not already been published to npm. Existing +releases are not published retroactively. If a run fails before publishing, +correct the setup problem and use **Re-run failed jobs**; source changes require +a new release tag. + ## Contributing 1. Fork the repository. From 09c7a496cb67d1c25b4d04b1e9cb375516a4f724 Mon Sep 17 00:00:00 2001 From: Manos Kalaitzoglou Date: Tue, 29 Sep 2026 10:09:10 +0300 Subject: [PATCH 2/2] docs: shorten npm release note --- TypeScript/README.md | 44 +------------------------------------------- 1 file changed, 1 insertion(+), 43 deletions(-) diff --git a/TypeScript/README.md b/TypeScript/README.md index dfedc7d..4e4bd1d 100644 --- a/TypeScript/README.md +++ b/TypeScript/README.md @@ -278,49 +278,7 @@ pnpm lint The build writes compiled files and declarations to `dist/`. -## Publishing releases - -The [`Publish to npm` workflow](../.github/workflows/npm-publish.yml) publishes -`@arcweave/arcscript` when a GitHub release is published. It checks out the release -tag, generates the parsers, installs dependencies from the lockfile, builds the -package, and runs the tests before publishing with provenance. - -### One-time npm setup - -An npm package maintainer must add a GitHub Actions trusted publisher in the -[`@arcweave/arcscript` package settings](https://www.npmjs.com/package/@arcweave/arcscript/access): - -| Setting | Value | -| --- | --- | -| Organization or user | `arcweave` | -| Repository | `arcscript-interpreters` | -| Workflow filename | `npm-publish.yml` | -| Environment name | Leave empty | -| Allowed actions | Enable direct publishing with `npm publish` | - -The workflow uses npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) -through GitHub Actions OIDC. No `NPM_TOKEN` repository secret is needed. -Merge the workflow into `main` and configure the trusted publisher before making -the next release. - -### Making a release - -1. Update `version` in `TypeScript/package.json` and merge the change into `main`. - For example, run `pnpm version 3.2.0 --no-git-tag-version` from `TypeScript/`. -2. Create a GitHub release from that commit with a matching tag, such as `v3.2.0` - or `3.2.0`. Both tag formats are supported; a mismatch fails the workflow. -3. Publish the GitHub release. Stable versions are published to npm's `latest` tag. - Prerelease versions, such as `3.2.0-beta.1`, are published to `next` and can be - installed with `npm install @arcweave/arcscript@next`. GitHub prereleases must - use a prerelease package version. To release a stable version afterward, bump - to `3.2.0` and publish a new release with its own matching tag. -4. Check the `Publish to npm` run in the repository's Actions tab. - -Saving a draft release or pushing a tag alone does not publish to npm. Each -release needs a version that has not already been published to npm. Existing -releases are not published retroactively. If a run fails before publishing, -correct the setup problem and use **Re-run failed jobs**; source changes require -a new release tag. +New GitHub releases are automatically published to [npmjs.com](https://www.npmjs.com/package/@arcweave/arcscript). ## Contributing