From eb34b9337815dc427c5fc4b704ec1d08be3982f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Wed, 28 Oct 2026 17:49:37 -0300 Subject: [PATCH 1/4] docs(release): document the Homebrew formula bump ethlambda now has a formula in lambdaclass/homebrew-tap, so a release is not finished until the formula points at it. The bump is manual, like ethrex's: hash the tag's source tarball, repackage the macOS release binary as the Apple silicon bottle, attach it to an ethlambda-vX.Y.Z tap release, and open the formula PR. --- RELEASE.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 62 insertions(+), 6 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 6ee3fc54e..0fdbd2316 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,8 +1,9 @@ # Releasing ethlambda This document describes how we publish and distribute ethlambda: Docker images on -GitHub Container Registry (`ghcr.io/lambdaclass/ethlambda`) and binaries attached -to [GitHub Releases](https://github.com/lambdaclass/ethlambda/releases). +GitHub Container Registry (`ghcr.io/lambdaclass/ethlambda`), binaries attached +to [GitHub Releases](https://github.com/lambdaclass/ethlambda/releases), and a +Homebrew formula in [lambdaclass/homebrew-tap](https://github.com/lambdaclass/homebrew-tap). A release is cut as a **release candidate** (`vX.Y.Z-rc.N`), tested, and then **promoted** to the final version (`vX.Y.Z`). Promotion re-publishes the tested @@ -203,19 +204,74 @@ in this order, and drop the boxes that do not apply: > - ``` -### 6. Merge the release branch +### 6. Update the Homebrew formula + +The `ethlambda` formula in [lambdaclass/homebrew-tap](https://github.com/lambdaclass/homebrew-tap) +builds from the final tag's source tarball. Apple silicon gets a bottle instead, +repackaged from the release's `ethlambda-macos-aarch64` binary, so it installs +the same binary the release ships; every other platform builds from source. The +bottle is attached to a tap release tagged `ethlambda-vX.Y.Z`, because the tap's +bare `vX.Y.Z` tags are ethrex's. + +Set the released version once; the commands below are then copy/paste: + +```bash +export V=X.Y.Z # no `v` prefix +``` + +1. Hash the source tarball. GitHub generates it from the final tag, so the tag + must be on the tested commit (step 5) before this hash is taken: + + ```bash + gh release download "v$V" -R lambdaclass/ethlambda --archive=tar.gz + shasum -a 256 "ethlambda-$V.tar.gz" + ``` + +2. Build the bottle from the release binary and hash it. The `ethlambda` + directory is the bottle root, laid out as `ethlambda//bin/ethlambda`: + + ```bash + gh release download "v$V" -R lambdaclass/ethlambda -p ethlambda-macos-aarch64 -p SHA256SUMS + shasum -a 256 -c --ignore-missing SHA256SUMS + chmod +x ethlambda-macos-aarch64 + mkdir -p "ethlambda/$V/bin" + mv ethlambda-macos-aarch64 "ethlambda/$V/bin/ethlambda" + # Keep macOS extended attributes (quarantine, provenance) out of the archive. + tar --no-xattrs --no-mac-metadata -czf "ethlambda-$V.arm64_sonoma.bottle.tar.gz" ethlambda + shasum -a 256 "ethlambda-$V.arm64_sonoma.bottle.tar.gz" + ``` + +3. Create the tap release with the bottle attached. It must exist before the + formula PR is opened, since the tap's CI installs from it. `--latest=false` + leaves the tap's latest release on ethrex's: + + ```bash + gh release create "ethlambda-v$V" -R lambdaclass/homebrew-tap --latest=false \ + --title "ethlambda v$V" --notes "ethlambda v$V bottle (arm64_sonoma)." \ + "ethlambda-$V.arm64_sonoma.bottle.tar.gz" + ``` + +4. In the tap's `Formula/ethlambda.rb`, update the `url`, both `sha256` values + and the bottle's `root_url`, plus the `rustup toolchain install` version if + `rust-toolchain.toml` changed. Open a PR: its `Formula CI` installs the + formula from the bottle and from source, and `brew test-bot` builds it on + Linux and Intel macOS. + +### 7. Merge the release branch Open a PR from `release/vX.Y.Z` into `main` and merge it, so the version bump and any candidate fixes land on `main`. ## Distribution channels -Releases are published to GitHub Releases and GHCR only. Not covered yet: +Releases are published to GitHub Releases, GHCR, and the +[lambdaclass/tap](https://github.com/lambdaclass/homebrew-tap) Homebrew tap +(`brew install lambdaclass/tap/ethlambda`). Not covered yet: - **crates.io**: not possible while the workspace depends on `leanvm` from git, since crates.io rejects crates with git dependencies. -- **apt and Homebrew**: future work. Either would be fed from the promoted - release's binaries, after the release is promoted. +- **apt**: future work. It would be fed from the promoted release's binaries, + after the release is promoted. ## Troubleshooting From 8e7d5ea71d2a317d0441e404a3dd064c0a2c5aba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Wed, 28 Oct 2026 18:18:41 -0300 Subject: [PATCH 2/4] docs(release): say test-bot skips Intel macOS for the formula Homebrew ships no Intel rustup bottle, so test-bot skips every rustup-based formula on macos-15-intel, ethrex included. The step claimed Intel coverage that does not exist. --- RELEASE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 0fdbd2316..0d76a98b7 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -254,8 +254,9 @@ export V=X.Y.Z # no `v` prefix 4. In the tap's `Formula/ethlambda.rb`, update the `url`, both `sha256` values and the bottle's `root_url`, plus the `rustup toolchain install` version if `rust-toolchain.toml` changed. Open a PR: its `Formula CI` installs the - formula from the bottle and from source, and `brew test-bot` builds it on - Linux and Intel macOS. + formula from the bottle and from source on macOS Sonoma, and `brew test-bot` + builds it on Linux and on Apple silicon macOS. test-bot skips Intel macOS, + which has no `rustup` bottle, so no CI builds the formula there. ### 7. Merge the release branch From 3dc0351a36dbc9c2c9caba34fbf99f7605ff6455 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Wed, 28 Oct 2026 18:30:37 -0300 Subject: [PATCH 3/4] docs(release): set the formula's commit on each Homebrew bump The formula now passes the tag's commit to vergen, since a tarball build has no checkout to read it from. That is one more value the bump has to update, and the tap's CI fails when it is stale. --- RELEASE.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 0d76a98b7..8642190d8 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -251,12 +251,20 @@ export V=X.Y.Z # no `v` prefix "ethlambda-$V.arm64_sonoma.bottle.tar.gz" ``` -4. In the tap's `Formula/ethlambda.rb`, update the `url`, both `sha256` values - and the bottle's `root_url`, plus the `rustup toolchain install` version if - `rust-toolchain.toml` changed. Open a PR: its `Formula CI` installs the - formula from the bottle and from source on macOS Sonoma, and `brew test-bot` - builds it on Linux and on Apple silicon macOS. test-bot skips Intel macOS, - which has no `rustup` bottle, so no CI builds the formula there. +4. In the tap's `Formula/ethlambda.rb`, update the `url`, both `sha256` values, + the bottle's `root_url`, and `VERGEN_GIT_SHA`, plus the `rustup toolchain + install` version if `rust-toolchain.toml` changed. A source build has no + checkout to read its commit from, so `VERGEN_GIT_SHA` is what its + `--version` reports; set it to the tag's abbreviated commit: + + ```bash + gh api "repos/lambdaclass/ethlambda/commits/v$V" --jq '.sha[0:7]' + ``` + + Open a PR: its `Formula CI` installs the formula from the bottle and from + source on macOS Sonoma, and fails if either `--version` misses that commit. + `brew test-bot` builds it on Linux and on Apple silicon macOS. test-bot skips + Intel macOS, which has no `rustup` bottle, so no CI builds the formula there. ### 7. Merge the release branch From fd696269a03b0aee5cae220e59691d2b42815536 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Wed, 28 Oct 2026 18:36:12 -0300 Subject: [PATCH 4/4] Revert "docs(release): set the formula's commit on each Homebrew bump" This reverts commit 3dc0351a36dbc9c2c9caba34fbf99f7605ff6455. --- RELEASE.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 8642190d8..0d76a98b7 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -251,20 +251,12 @@ export V=X.Y.Z # no `v` prefix "ethlambda-$V.arm64_sonoma.bottle.tar.gz" ``` -4. In the tap's `Formula/ethlambda.rb`, update the `url`, both `sha256` values, - the bottle's `root_url`, and `VERGEN_GIT_SHA`, plus the `rustup toolchain - install` version if `rust-toolchain.toml` changed. A source build has no - checkout to read its commit from, so `VERGEN_GIT_SHA` is what its - `--version` reports; set it to the tag's abbreviated commit: - - ```bash - gh api "repos/lambdaclass/ethlambda/commits/v$V" --jq '.sha[0:7]' - ``` - - Open a PR: its `Formula CI` installs the formula from the bottle and from - source on macOS Sonoma, and fails if either `--version` misses that commit. - `brew test-bot` builds it on Linux and on Apple silicon macOS. test-bot skips - Intel macOS, which has no `rustup` bottle, so no CI builds the formula there. +4. In the tap's `Formula/ethlambda.rb`, update the `url`, both `sha256` values + and the bottle's `root_url`, plus the `rustup toolchain install` version if + `rust-toolchain.toml` changed. Open a PR: its `Formula CI` installs the + formula from the bottle and from source on macOS Sonoma, and `brew test-bot` + builds it on Linux and on Apple silicon macOS. test-bot skips Intel macOS, + which has no `rustup` bottle, so no CI builds the formula there. ### 7. Merge the release branch