Release FrameSeq#

FrameSeq can publish both npm packages from a version tag through GitHub Actions and npm Trusted Publishing. The workflow uses short-lived OpenID Connect credentials, so the repository does not need a long-lived npm write token.

One-time npm configuration#

Configure a Trusted Publisher separately for both packages:

• @pride7/frameseq
• create-frameseq

On each package's npm Settings → Trusted Publisher page, use:

Provider: GitHub Actions
Organization or user: pride7
Repository: frameseq
Workflow filename: publish.yml
Environment: leave empty
Allowed action: npm publish

The workflow is stored at .github/workflows/publish.yml. Both packages may trust the same workflow file.

Prepare a release#

Update all four version references:

1. the root package.json version;
2. the root package-lock.json package versions;
3. packages/create-frameseq/package.json;
4. FRAMESEQ_VERSION in packages/create-frameseq/index.mjs.

The standalone StackBlitz project's @pride7/frameseq dependency in examples/playground/package.json must also match the new framework version. Move the relevant Changelog entries from Unreleased into a dated version section.

Run the local gate:

npm run release:tag-check -- v0.16.0
npm run release:check

Commit and push the release changes before creating the tag, and let CI pass on them. CI runs release:check in four groups side by side, as node scripts/test-suite.mjs core, studio (with pack:check), app, and exports, and node scripts/test-suite.mjs studio runs one group locally.

Publish from a tag#

Create a tag that exactly matches the root package version:

git tag -a v0.16.0 -m "FrameSeq 0.16.0"
git push origin v0.16.0

The workflow then:

1. verifies that the tag, framework version, creator template, and playground dependency agree;
2. waits for CI to have passed on the tagged commit, the run of its push to main or else the one the tag starts, rather than running release:check a second time, and stops if it failed;
3. publishes @pride7/frameseq and create-frameseq in separate jobs.

The two publish jobs are independent. If one transiently fails, rerun only its failed job from GitHub Actions rather than creating another tag.

Verify the registry#

npm view @pride7/frameseq version
npm view create-frameseq version

Do not move or recreate a published version tag. npm package name-and-version pairs cannot be reused.

The desktop app#

The same version tag starts the Desktop app workflow (.github/workflows/app.yml), which builds the FrameSeq app on each platform and attaches it to the GitHub release of that tag, creating the release when it does not exist yet:

Each job runs node scripts/app-bundle.mjs --platform <platform> --arch <arch>. The script packs the package as npm would, installs its production dependencies and the optional typesetters for the target with npm install --os --cpu, downloads the Node.js release named by --node and checks it against the published checksums, adds a headless browser for macOS and Linux, builds the Studio's window from desktop/ with Rust, and writes the launchers and the installer. The window is built on the system it is for, which is why Linux on ARM has a runner of its own; the Intel Mac's is cross-compiled on Apple silicon. Run it locally to try a build; without Inno Setup, Windows gets only the zip, and away from macOS the Mac app is zipped instead of put in a disk image.

The release job attaches the apps to the release with SHA256SUMS.txt, which lists the SHA-256 of each, so that a download can be checked against it.

Run the workflow by hand from GitHub Actions to build the apps without a release; they are then kept as workflow artifacts. The apps are not signed or notarised yet.

Updates to the app#

An installed app updates itself from the package published to npm, without the release's downloads, when nothing it ships around FrameSeq has to change; see Updates. What it ships around FrameSeq is its runtime: Node.js, desktop/, scripts/app-bundle.mjs, and scripts/app-launch.mjs. node scripts/app-runtime.mjs prints the runtime's fingerprint, and the build writes it into the app. The publish job stamps it into the published package.json as appRuntime (node scripts/app-runtime.mjs --stamp), so nothing needs bumping by hand. An app takes a published version only when the version's appRuntime is its own, its dependencies satisfy the version's, and its Node.js satisfies engines. So a release that changes the window, Node.js, or a dependency reaches existing apps as a new download, and any other release updates them in place.