Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion .github/workflows/gh-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
94 changes: 94 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
17 changes: 17 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 6 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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 }} \
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 23 additions & 0 deletions dev/extract-changelog.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
#!/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
echo "Usage: $0 <version>"
echo " Example: $0 v0.2.0"
echo " Example: $0 Prerelease"
exit 1
fi

version=$1

awk -v ver="$version" '
/^## \[.*\]/ {
# Stop at the next version heading once the requested section has started.
if (p) exit
# 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
Comment thread
simongdavies marked this conversation as resolved.
Resolved
61 changes: 56 additions & 5 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -51,22 +94,25 @@ 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).

Both crates.io and established npm packages use trusted publishing (OIDC), so they do not need long-lived publishing tokens. A new npm package needs a short-lived `NPM_TOKEN` for its first release, as described below. Provenance attestations are generated for every npm package.

### 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.

Expand Down Expand Up @@ -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.
Expand Down