From a5b33166e9f7c855e84b867ada2cfbc365663c64 Mon Sep 17 00:00:00 2001 From: Simon Davies Date: Thu, 19 Nov 2026 21:23:23 +0000 Subject: [PATCH 1/2] Add a changelog Signed-off-by: Simon Davies --- .github/workflows/gh-publish.yml | 13 ++++- CHANGELOG.md | 94 ++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 17 ++++++ Justfile | 6 ++ README.md | 3 + dev/extract-changelog.sh | 18 ++++++ docs/release.md | 61 +++++++++++++++++++-- 7 files changed, 206 insertions(+), 6 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 dev/extract-changelog.sh diff --git a/.github/workflows/gh-publish.yml b/.github/workflows/gh-publish.yml index 6cf16df1..4cae74f5 100644 --- a/.github/workflows/gh-publish.yml +++ b/.github/workflows/gh-publish.yml @@ -40,6 +40,17 @@ jobs: fetch-depth: 0 fetch-tags: true + - name: Hyperlight setup + uses: hyperlight-dev/ci-setup-workflow@59673866360458f8dd035f4a9fa766aeebad2038 # v2.3.1 + with: + just-version: "1.51" + + - name: Generate release notes from the changelog and merged PRs + env: + GH_TOKEN: ${{ github.token }} + NOTES_TAG: ${{ inputs.dry_run && 'dev-latest' || format('v{0}', inputs.version) }} + run: just create-release-notes "$NOTES_TAG" > RELEASE_NOTES.md + - name: Download benchmarks (Windows) uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8 with: @@ -68,7 +79,7 @@ jobs: if: ${{ !inputs.dry_run }} run: | gh release create v${{ inputs.version }} \ - --generate-notes \ + --notes-file RELEASE_NOTES.md \ benchmarks_Windows_whp.tar.gz \ benchmarks_Linux_kvm.tar.gz \ benchmarks_Linux_hyperv3.tar.gz diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..0b1f3de5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,94 @@ +# Changelog + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +This file records significant changes since [v0.5.0](https://github.com/hyperlight-dev/hyperlight-js/releases/tag/v0.5.0). +Release notes also include GitHub's automatically generated list of merged pull requests. + +## [Prerelease] - Unreleased + +### Changed + +- **Breaking:** Upgrade Hyperlight from 0.18 to 0.19 and remove the separate guest + heap setting: Rust `SandboxBuilder::with_guest_heap_size` and Node.js + `SandboxBuilder.setHeapSize` no longer exist. Use `with_guest_scratch_size` / + `setScratchSize` instead. Scratch now shares one budget across the heap, stack, + transport pools, page tables, and copy-on-write pages, with a default and minimum + of 5 MiB. It is not a JavaScript-only heap allowance; re-evaluate memory budgets + when migrating. Exhaustion aborts and poisons the sandbox; restore a snapshot + before reuse. ([#429](https://github.com/hyperlight-dev/hyperlight-js/pull/429)) +- **Breaking:** Snapshot metadata now uses schema version 2. Snapshots produced by + v0.5.0 are rejected because their base may not have registered the host functions + recorded in metadata. Recreate persisted snapshots with the new runtime rather + than editing their metadata. The Hyperlight 0.19 upgrade also changes the + underlying snapshot ABI. + ([#422](https://github.com/hyperlight-dev/hyperlight-js/pull/422), + [#429](https://github.com/hyperlight-dev/hyperlight-js/pull/429)) +- **Breaking for custom native runtimes:** Upgrade `rquickjs` from 0.12 to 0.14, + including its QuickJS engine update. Update custom runtime dependencies to + `rquickjs = "0.14"` and rebuild guests. Upstream buffer/typed-array byte accessors + are now unsafe, their safe `AsRef` implementations are removed, and raw buffer + accessors return slice pointers. Review custom modules against the + [upstream migration notes](https://github.com/DelSkayn/rquickjs/blob/v0.14.0/CHANGELOG.md). + ([#326](https://github.com/hyperlight-dev/hyperlight-js/pull/326)) +- Host and guest builds now use separate pinned Rust toolchains. The standard + `just` build recipes install both, allowing host dependencies to advance without + changing the guest compiler. Update the module resolver to `oxc_resolver` + 11.24.3. + ([#389](https://github.com/hyperlight-dev/hyperlight-js/pull/389), + [#390](https://github.com/hyperlight-dev/hyperlight-js/pull/390)) +- Update observability dependencies to `tracing-opentelemetry` 0.34 and + `tracing-tracy` 0.12. + ([#356](https://github.com/hyperlight-dev/hyperlight-js/pull/356), + [#413](https://github.com/hyperlight-dev/hyperlight-js/pull/413)) +- Update the MCP server example to `@modelcontextprotocol/sdk` 1.32.2 and Hono + 4.13.18. + ([#387](https://github.com/hyperlight-dev/hyperlight-js/pull/387), + [#439](https://github.com/hyperlight-dev/hyperlight-js/pull/439)) +- CI now separates code checks from builds, restores primed Rust and guest sysroot + caches, uses shorter benchmarks, and skips expensive jobs for documentation-only + PRs. Group Hyperlight dependency updates so host and guest versions stay aligned. + ([#399](https://github.com/hyperlight-dev/hyperlight-js/pull/399), + [#438](https://github.com/hyperlight-dev/hyperlight-js/pull/438)) + +### Removed + +- **Breaking (Rust):** Remove `ProtoJSSandbox::set_module_loader`, `host_module`, + and `register`. Configure resources before `build()` using + `SandboxBuilder::with_module_loader` and `with_host_function_modules`, supplying + `HostFunctionModule` values. `HostModule` is now internal. + ([#448](https://github.com/hyperlight-dev/hyperlight-js/pull/448)) +- **Breaking (Node.js):** Remove `ProtoJSSandbox.hostModule`, `register`, and the + `HostModule` export. Create `HostFunctionModule` instances and pass them to + `SandboxBuilder.setHostFunctionModules` before `build()`. + ([#448](https://github.com/hyperlight-dev/hyperlight-js/pull/448)) +- **Breaking:** Remove deprecated Rust `with_guest_input_buffer_size` / + `with_guest_output_buffer_size` and Node.js `setInputBufferSize` / + `setOutputBufferSize`. Use `with_input_transport_pool_pages` / + `with_output_transport_pool_pages` or `setInputTransportPoolPages` / + `setOutputTransportPoolPages` for explicit pool budgets, and the corresponding + transport-buffer-size setters for individual buffers. Pool budgets are in pages, + not bytes; this is not a direct rename. + ([#448](https://github.com/hyperlight-dev/hyperlight-js/pull/448)) +- **Breaking:** Remove `JSSandbox::poisoned()` and `LoadedJSSandbox::poisoned()`; + use `status().is_poisoned()`. In Node.js, replace the removed `poisoned` getter + with `status === 'poisoned'`. + ([#448](https://github.com/hyperlight-dev/hyperlight-js/pull/448)) + +### Fixed + +- Avoid redundant host-function registration during load/unload cycles. Restoring + a snapshot with different host functions registers them once and updates the + base snapshot, so subsequent cycles avoid unnecessary guest calls. + ([#422](https://github.com/hyperlight-dev/hyperlight-js/pull/422)) +- Fix Windows rebuild failures caused by losing the Hyperlight surrogate + executable from the build output directory. + ([#404](https://github.com/hyperlight-dev/hyperlight-js/pull/404), + [#429](https://github.com/hyperlight-dev/hyperlight-js/pull/429)) +- Publish all existing npm platform packages, including ARM64, using trusted + publishing. Reruns after a partial release skip already-published versions, + and successful publishes no longer fail a premature registry visibility check. + ([#401](https://github.com/hyperlight-dev/hyperlight-js/pull/401)) +- Remove an unsupported toolchain input from CI setup. + ([#405](https://github.com/hyperlight-dev/hyperlight-js/pull/405)) + +[Prerelease]: https://github.com/hyperlight-dev/hyperlight-js/compare/v0.5.0...HEAD diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index acad3047..85c33c46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,23 @@ All contributions come through pull requests. To submit a proposed change, we re 6. Wait for the CI process to finish and make sure all checks are green 7. A maintainer of the project will be assigned, and you can expect a review within a few days +#### Changelog entries + +Include significant and user-facing changes in the `[Prerelease] - Unreleased` +section of [CHANGELOG.md](CHANGELOG.md) as part of your PR. Follow +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/): use `Added`, `Changed`, +`Deprecated`, `Removed`, `Fixed`, or `Security` headings, and link each entry to +its PR. Routine dependency bumps and internal-only changes need not have entries; +GitHub's generated PR list is included in release notes as well. + +Mark every breaking change with **Breaking:** and describe the affected Rust and +Node.js APIs, replacement APIs, changed units/defaults, and any required snapshot +or guest rebuilds. Also apply the `breaking-change` label, in addition to the +required `kind/*` label; labels alone do not populate the curated changelog. + +Reviewers should check changelog completeness and migration guidance. +Release preparation and note previews are described in [the release checklist](docs/release.md). + #### Use work-in-progress PRs for early feedback A good way to communicate before investing too much time is to create a "Work-in-progress" PR and share it with your reviewers. The standard way of doing this is to add a "[WIP]" prefix in your PR's title and open the pull request as a draft. diff --git a/Justfile b/Justfile index 68e86366..5098f8ee 100644 --- a/Justfile +++ b/Justfile @@ -50,6 +50,12 @@ check: check-license-headers: ./dev/check-license-headers.sh +# Use dev-latest for the Prerelease section, or a release tag such as v0.6.0. +@create-release-notes tag: + echo "## What's Changed" + bash dev/extract-changelog.sh {{ if tag == "dev-latest" { "Prerelease" } else { tag } }} + gh api repos/{owner}/{repo}/releases/generate-notes -f tag_name={{ tag }} | jq -r '.body' | sed '1,/## What'"'"'s Changed/d' + clippy target=default-target features="": (ensure-tools) cd src/hyperlight-js-runtime && cargo hyperlight clippy -p hyperlight-js-runtime \ --target={{ guest-target }} \ diff --git a/README.md b/README.md index deac1743..3eae9ee0 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,9 @@ Provides a capability to run JavaScript inside of Hyperlight using quickjs as th ## Documentation +- [Changelog](CHANGELOG.md) - Significant changes and breaking-change migrations +- [Release checklist](docs/release.md) - Preparing and publishing releases + - [Custom guest runtimes](docs/extending-runtime.md) - Extend with native modules and build and embed a custom guest using cargo-hyperlight - [Execution Monitors](docs/execution-monitors.md) - Timeout and resource limit enforcement for handler execution diff --git a/dev/extract-changelog.sh b/dev/extract-changelog.sh new file mode 100644 index 00000000..9eb39b9d --- /dev/null +++ b/dev/extract-changelog.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +if [[ $# -lt 1 ]]; then + echo "Usage: $0 " + echo " Example: $0 v0.2.0" + echo " Example: $0 Prerelease" + exit 1 +fi + +version=$1 + +awk -v ver="$version" ' +/^## \[.*\]/ { + if (p) exit + if ($0 ~ "^## \\[" ver "\\]") { p=1; next } +} +p' CHANGELOG.md diff --git a/docs/release.md b/docs/release.md index 12e000bf..514fc299 100644 --- a/docs/release.md +++ b/docs/release.md @@ -34,6 +34,49 @@ Create a PR with these changes and merge it into the `main` branch. > **Note:** The release workflow sets all npm versions from the tag before publishing. +## Prepare the changelog + +Like Hyperlight, we maintain a curated [CHANGELOG.md](../CHANGELOG.md) using +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). It supplies the highlights +at the start of release notes; GitHub's generated PR list follows them. Do not +replace the curated entries with generated PR titles. + +Before tagging, include these changes in the release-preparation PR: + +1. Audit PRs merged since the previous release against the changelog, including + dependency updates with user-visible effects. Record significant changes and + explicitly mark **Breaking:** entries with migration instructions for Rust, + Node.js, custom guests, and persisted snapshots where applicable. Do not rely + solely on PR labels to find breaking changes. +2. Rename `## [Prerelease] - Unreleased` to, for example, + `## [v0.18.0] - YYYY-MM-DD`, using the actual release date. +3. Add a new empty `## [Prerelease] - Unreleased` section at the top for the next + release. +4. Update the comparison links at the bottom, for example: + + ```markdown + [Prerelease]: https://github.com/hyperlight-dev/hyperlight-js/compare/v0.18.0...HEAD + [v0.18.0]: https://github.com/hyperlight-dev/hyperlight-js/compare/v0.17.0...v0.18.0 + ``` + +5. From the repository root, preview the notes with an authenticated + GitHub CLI: + + ```console + just create-release-notes v0.18.0 + ``` + + Before a version has been prepared, use `just create-release-notes dev-latest` + to preview the current `Prerelease` section. These commands combine the + extracted changelog section with GitHub's generate-notes API output; they do + not publish anything. When working in a fork, set + `GH_REPO=hyperlight-dev/hyperlight-js` to preview upstream PR notes. + +Review the preview for accuracy and completeness, merge the preparation PR, and +tag that commit. The release workflow uses the same recipe to generate the notes +passed to `gh release create --notes-file`. Dry runs use the `Prerelease` section +and publish nothing. + ## Create a tag When the `main` branch has reached a state in which you want to release a new Cargo version, you should create a tag. Although you can do this from the GitHub releases page, we currently recommend doing the tag from the command line. Do so with the following commands: @@ -51,7 +94,7 @@ If you are creating a patch release see the instructions [here](#patching-a-rele Pushing a `vX.Y.Z` tag is the **only** manual trigger you need — you do **not** run any workflow by hand. The tag push starts the ["Create a Release"](https://github.com/hyperlight-dev/hyperlight-js/actions/workflows/CreateRelease.yml) workflow ([`CreateRelease.yml`](https://github.com/hyperlight-dev/hyperlight-js/blob/main/.github/workflows/CreateRelease.yml)), which reads the version from the tag and then does everything else automatically: 1. **Creates the release branch** — a `release/v0.18.0` branch is created and pushed for you. -2. **Creates the GitHub release** — a new [GitHub release](https://github.com/hyperlight-dev/hyperlight-js/releases) is published with automatically generated release notes and the benchmark results attached. +2. **Creates the GitHub release** — a new [GitHub release](https://github.com/hyperlight-dev/hyperlight-js/releases) is published with curated changelog highlights followed by GitHub-generated PR notes, and the benchmark results attached. 3. **Publishes the crates to crates.io** — in dependency order (`hyperlight-js-common` → `hyperlight-js-runtime` → `hyperlight-js`). Verify on the [hyperlight-js page on crates.io](https://crates.io/crates/hyperlight-js). 4. **Publishes the npm packages to npmjs.com** — `@hyperlight-dev/js-host-api` and its platform-specific binary packages, with their versions set from the tag. Verify on the [npmjs.com package page](https://www.npmjs.com/package/@hyperlight-dev/js-host-api). @@ -59,14 +102,17 @@ Both crates.io and established npm packages use trusted publishing (OIDC), so th ### Release-note labels -GitHub generates release notes from merged pull-request titles and labels using -`.github/release.yml`. Commit messages, including conventional-commit -`BREAKING CHANGE` footers, are not used for categorization. +GitHub generates the full PR-list portion of release notes from merged +pull-request titles and labels using [`.github/release.yml`](../.github/release.yml). +Commit messages, including conventional-commit `BREAKING CHANGE` footers, are not +used for categorization. Curated highlights come from `CHANGELOG.md`, independently +of these labels. Any pull request that breaks a released API must have the `breaking-change` label so it appears under **Breaking Changes**. This is in addition to the single required `kind/*` label enforced by `PRLabelChecker.yml`. Describe the -affected Rust and Node APIs and their migration in the pull-request body. +affected Rust and Node APIs and their migration in the pull-request body and +the changelog. > **Note:** Only a `vX.Y.Z` **tag** push triggers a real release. Pushing to `main`, or running the workflow manually with **Run workflow**, performs a **dry run** — it builds and validates everything but publishes nothing. @@ -118,6 +164,11 @@ If you need to update a previously released version of hyperlight-js then you sh Once the PR is merged, then you should follow the instructions above. In this instance the version number of the tag should be a patch version, for example if you are patching the `release/v0.18.0` branch and this is the first patch release to that branch then the tag should be `v0.18.1`. If you are patching a patch release then the tag should be `v0.18.2` and the target branch should be `release/v0.18.1` and so on. +Prepare the patch version's dated changelog section on the branch being tagged. +Include only changes shipped in that patch, retain its existing release history, +and compare the patch tag against the previous patch/base release. Do not copy +unreleased entries from `main` unless those changes are included in the patch. + ## Manual npm publishing (emergency only) > ⚠️ **Do not use this for regular releases.** Use the `CreateRelease` workflow instead. Manual publishing uses `NPM_TOKEN` instead of OIDC trusted publishing. It still generates provenance attestations, but the release will not show the "Published via trusted publishing" badge on npmjs.com. Only use this if the automated release pipeline is broken and you need to ship an urgent fix. From a20975f373193dfa73b51dfad10e3b8356979ced Mon Sep 17 00:00:00 2001 From: Simon Davies Date: Fri, 20 Nov 2026 07:30:34 +0000 Subject: [PATCH 2/2] fix version matching, add comments Signed-off-by: Simon Davies --- dev/extract-changelog.sh | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/dev/extract-changelog.sh b/dev/extract-changelog.sh index 9eb39b9d..555d644f 100644 --- a/dev/extract-changelog.sh +++ b/dev/extract-changelog.sh @@ -1,4 +1,6 @@ #!/usr/bin/env bash +# Print one version's release notes from CHANGELOG.md in the current directory, +# excluding its heading. A missing version produces no output and is not an error. set -Eeuo pipefail if [[ $# -lt 1 ]]; then @@ -12,7 +14,10 @@ version=$1 awk -v ver="$version" ' /^## \[.*\]/ { + # Stop at the next version heading once the requested section has started. if (p) exit - if ($0 ~ "^## \\[" ver "\\]") { p=1; next } + # Match the version literally; enable printing and skip the heading itself. + if (index($0, "## [" ver "]") == 1) { p=1; next } } +# Print each line while inside the requested section (p is the printing flag). p' CHANGELOG.md