Releasing

View Source

What to do for a release of erlang-wasmtime, and separately for a Wasmtime version bump. You need push rights, gh, and a machine of each architecture (x86_64 and aarch64) for the shims.

Release the library

  1. CHANGELOG.md: turn "unreleased" into the version and date.
  2. src/erlang_wasmtime.app.src: bump vsn.
  3. make check on a full build; the ASan and runtime-only recipes in CONTRIBUTING.md if the NIF changed since the last release.
  4. Commit, tag v<version>, push the tag. CI runs on the tag.
  5. rebar3 hex publish. The package holds src/, c_src/, scripts/, priv/shims/ and the docs; the CI job "Hex package stays under the 8 MB cap" is the size check. The Wasmtime library is not in the package; it is downloaded at build time.

Bump Wasmtime

The pinned version is scripts/wasmtime.version. Everything below is tied to it: the upstream archives, this repo's runtime archives, the CLI that compiles the shims, the precompiled fixtures.

  1. Edit scripts/wasmtime.version.
  2. Download the six upstream C API archives (x86_64 and aarch64 for linux, musl, macos) and replace their lines in scripts/wasmtime.sha256.
  3. Set scripts/wasmtime-runtime.rev to 1 for a new Wasmtime version (bump it instead when only the build recipe changed), then run the runtime workflow: gh workflow run wasmtime-runtime.yml. It builds the runtime-only library on native runners for every platform plus the full FreeBSD library, and attaches them to the release wasmtime-runtime-<version>-r<rev>. Assets are immutable: a rebuild gets a new revision and a new release, so a tagged erlang_wasmtime always downloads exactly what it pinned. Paste the workflow's SHA256SUMS into scripts/wasmtime-runtime.sha256 and the FreeBSD line into scripts/wasmtime.sha256.
  4. Any change to scripts/build-wasmtime.sh or the workflow after the archives were built means step 3 again with a bumped revision before the release: the archives must come from the recipe the tag ships.
  5. Pin the CLI archives (wasmtime-<version>-aarch64-macos.tar.xz and x86_64-linux) in scripts/wasmtime-cli.sha256, then run scripts/precompile-shims.sh on an aarch64 machine and on an x86_64 machine; commit the 14 files in priv/shims/. The flags in the script must match make_config() in c_src/nif_engine.c; shim_files_load in the tests fails when they drift.
  6. Check the C API for changes that matter here: wasmtime/conf.h feature macros, the wasmtime_val_t layout, the reference API (*_unroot signatures), wasi.h stdio hooks. docs/design.md lists what the code relies on.
  7. rebar3 compile && rebar3 ct on a full build, then the runtime-only recipe with fresh fixtures from scripts/precompile-fixtures.escript. The runtime-only CI job proves the full and runtime builds still accept the same precompiled modules.
  8. CHANGELOG.md: note the new Wasmtime version. README.md and docs/features.md mention the major version.