Skip to content

Human action 217

Jerry Holland edited this page Oct 18, 2026 · 8 revisions

Complete the v0.21.0 release

Closed 2026-10-18 as superseded (#289): trusted publishing is tracked on #139, and the release workflow runs the install check on a hosted Windows runner. Nothing below is still required.

Procedure for issue #217. The issue is the record of ownership, status and completion evidence; this page is the execution instruction.

Owner role: the repository owner (jwh3times), who holds push access for tags, the npm holland-vip organization, and a Windows machine for the install check.

What this completes: v0.21.0 is the cutover of ADR-0037: the first release whose installed cst is the Rust executable. The release candidate is 8cd4ae1fcc1facfc30908c1f1b27f23e2936aca2 on main.

When: as soon as practical. Until it is done, package.json and the README describe a release that does not exist.

Prerequisites

  • A Windows machine, for the install check in step 6 only. It needs PowerShell, Git and, for the npm half, Node.js. Nothing has to be built on it.
  • gh signed in with push access to jwh3times/causet.
  • An npm session for an owner of the holland-vip organization, with two-factor authentication. Node.js 22.14 or later and npm 11.5.1 or later. Check with npm whoami.
  • A Linux machine or container with Node.js and Git, for the last verification step. The Fedora checkout serves.

Step 0: nothing left to decide

Decided 2026-10-08.

  • The install channel. The owner accepted ADR-0038's third amendment: install scripts over the GitHub release assets are the primary way to install, and npm is the second (#218, #150).
  • The candidate. The owner moved it forward from 2510b81 so that v0.21.0 carries those scripts. It is now 8cd4ae1, the tip of main when this page was last updated. If main has moved since, tag the candidate, not the tip.

Step 1: confirm the two dispatched runs

Both were dispatched against 8cd4ae1 on 2026-10-08. Their results are recorded on #217 as they finish. Confirm before tagging:

  1. Open run 37873457601 (ci, manual dispatch). Expected: every job green, 15 of 15: six modes on Ubuntu and on Windows, plus two Node 20 jobs, plus static checks. This is release gate 3. A routine PR or main run does not satisfy it.
  2. Open run 37873459708 (release, manual dispatch). Expected: both build jobs, assemble the package set, and both install and smoke-test jobs green; the attest and draft the release job skipped. This is the package half of release gate 9. The smoke jobs install both ways, by npm and by the install script.
  3. If either failed, stop. Record the failing job on #217 and do not tag.

The earlier runs against 2510b81 (37855733995 and 37855736559) were green, and no longer count: they qualified a commit that is not the candidate.

Step 2: nothing to run on your own machine

Superseded 2026-10-09. This step used to be release gate 10: the benchmark on lab-windows-a. The owner decided that no release gate may depend on a maintainer's own machine, and gate 10 is now the deterministic benchmark check on GitHub-hosted runners (PR #222, release-gates.yml).

  • It passed on ubuntu-latest and windows-latest for the code v0.21.0 shipped: PR #222 changed only the workflow, the baseline and documentation.
  • The hosted Windows runner's counts equal lab-windows-a's exactly. The two "regressions" a Fedora host reported were a missing Linux baseline, not regressions.
  • A latency run on lab-windows-a is still useful evidence for performance work (npm run test:benchmark -- --host lab-windows-a). It gates nothing.

Step 3: tag the release

In any clean checkout with push access:

git fetch origin
git tag -a v0.21.0 8cd4ae1fcc1facfc30908c1f1b27f23e2936aca2 -m "causet 0.21.0"
git push origin v0.21.0

The tag starts the release workflow. Watch it:

gh run list --repo jwh3times/causet --workflow release.yml --limit 1
gh run watch --repo jwh3times/causet <run id>

Expected: every job green, including attest and draft the release, and publish to npm when enabled. Its Attest what a user downloads step runs; its Publish to npm with provenance step is skipped, because the repository variable NPM_PUBLISH is not set. A draft release named causet v0.21.0 now exists with these assets:

  • holland-vip-causet-0.21.0.tgz
  • holland-vip-causet-win32-x64-0.21.0.tgz
  • holland-vip-causet-linux-x64-gnu-0.21.0.tgz
  • cst-0.21.0-x86_64-pc-windows-msvc.zip
  • cst-0.21.0-x86_64-unknown-linux-gnu.tar.gz
  • install.sh and install.ps1
  • SHA256SUMS

If the tag is on the wrong commit: release tags are immutable under the repository's rulesets since 2026-10-09. Before anything is published, disable the ruleset "release tags are immutable" in the repository settings, delete and re-create the tag, delete the draft release, enable the ruleset again, and say so on #217.

Step 4: publish the three packages

This first publish of the platform packages is manual: npm configures a trusted publisher only on a package that exists (#139, step 4).

  1. Download the assets into an empty directory and check them:

    mkdir release-0.21.0 && cd release-0.21.0
    gh release download v0.21.0 --repo jwh3times/causet
    sha256sum --check --ignore-missing SHA256SUMS

    Expected: OK for all three .tgz files, both archives and both install scripts. On Windows without sha256sum, compare Get-FileHash -Algorithm SHA256 <file> with the line in SHA256SUMS.

  2. Publish the platform packages first, so the main package never names one that is absent:

    npm whoami
    npm publish holland-vip-causet-win32-x64-0.21.0.tgz --access public
    npm publish holland-vip-causet-linux-x64-gnu-0.21.0.tgz --access public
  3. Publish the main package:

    npm publish holland-vip-causet-0.21.0.tgz --access public
  4. Check all three. The registry can take several minutes to show a new version:

    npm view @holland-vip/causet-win32-x64@0.21.0 dist.shasum
    npm view @holland-vip/causet-linux-x64-gnu@0.21.0 dist.shasum
    npm view @holland-vip/causet@0.21.0 dist.shasum optionalDependencies bin

    Expected: each prints a shasum; the main package lists both platform packages at exactly 0.21.0 and bin of { cst: 'bin/native/cst.exe', vlab: 'bin/native/cst.exe' }.

If a publish fails: stop and record the exact npm error on #217. A version, once published, cannot be published again; do not retry with a changed tarball. If only the main package failed, the platform packages are harmless by themselves.

Step 5: publish the GitHub release

The install scripts download from a published release, so the release has to be public before they can be checked. A draft's assets are not served at releases/latest/download.

gh release edit v0.21.0 --repo jwh3times/causet --draft=false --latest \
  --notes "The cutover of ADR-0037: cst is now a native executable. See CHANGELOG.md, section 0.21.0."

Expected: gh release view v0.21.0 --repo jwh3times/causet shows it as the latest release.

Step 6: verify both ways of installing, on both platforms

Do this on the Windows host and on a Linux host. It is the first time the scripts download from a real release: CI only ever read the assets from a directory.

6a. By script, into a scratch prefix so nothing on the machine changes.

Linux:

curl -fsSLO https://github.com/jwh3times/causet/releases/latest/download/install.sh
sh install.sh --prefix ./script-prefix
./script-prefix/cst --version
mkdir repo && (cd repo && git init -q -b main && ../script-prefix/cst doctor)

Windows (PowerShell):

irm https://github.com/jwh3times/causet/releases/latest/download/install.ps1 -OutFile install.ps1
.\install.ps1 -Prefix .\script-prefix
.\script-prefix\cst.exe --version
mkdir repo; cd repo; git init -q -b main; ..\script-prefix\cst.exe doctor; cd ..

Expected: Installed causet 0.21.0 (<target>):, then causet 0.21.0, then a doctor report with "implementation": "rust", "node": null and "launcher": null.

  • If Windows blocks install.ps1 under its execution policy, run it as powershell -ExecutionPolicy Bypass -File .\install.ps1 -Prefix .\script-prefix, and note that on #217: the README's one-liner (irm ... | iex) is not subject to it.
  • If SmartScreen or Defender interferes with cst.exe, record exactly what it showed on #217. That is the "observed friction" ADR-0038 leaves the signing decision waiting on.
  • A refusal that names a SHA-256 mismatch means the release's assets and SHA256SUMS disagree. Stop and record it.

6b. The attestation. On either host, with the archive downloaded in step 4:

gh attestation verify cst-0.21.0-x86_64-unknown-linux-gnu.tar.gz --repo jwh3times/causet

Expected: a line saying the attestation was verified, naming release.yml. This step has never run before.

6c. By npm:

npm install -g --prefix ./npm-prefix --allow-scripts=@holland-vip/causet @holland-vip/causet@0.21.0

Then run ./npm-prefix/bin/cst on Linux or .\npm-prefix\cst.cmd on Windows with --version and doctor, as in 6a.

Expected: the same three doctor fields.

  • "launcher": "node" means the install script did not run. On npm 11 and earlier the flag is unknown and harmless; on npm 12 it is required. Reinstall with it.
  • A line on stderr naming a missing platform package means it was not installed. Check npm view from step 4 and the host's platform. Until v0.24.0 the launcher then ran the JavaScript CLI; from v0.24.0 it exits 1 (#243).

Remove the scratch directories afterwards.

Step 7 (after this release): trusted publishing

With all three packages on npm, finish #139 step 5: configure a trusted publisher for each (repository jwh3times/causet, workflow release.yml), disallow tokens, and set the repository variable NPM_PUBLISH to true. From the next release the tag publishes with provenance, and step 4 here is not needed.

#218 can be closed once step 6 has shown a download from the release and a verified attestation.

Completion evidence

Attach to #217:

  • the two run links from step 1 and the tag's run from step 3, with their conclusions;
  • the three package URLs and their dist.shasum values, beside the matching SHA256SUMS lines;
  • from step 6: the four doctor reports (script and npm, on each platform) with the npm version used, the gh attestation verify output, and anything SmartScreen, Defender or the execution policy did;
  • the release URL.

Then remove human-action-required from #217, set its board card to Done, and point the Human TODO entry at the completed outcome. #152 and #150 can then be closed, and #139 once step 7 is done.

Clone this wiki locally