How to Release an ethrex version

Releases are prepared from dedicated release branches and tagged using versioning.

1st - Create release branch

Branch name must follow the format release/vX.Y.Z.

Examples:

• release/v1.2.0
• release/v3.0.0
• release/v3.2.0

2nd - Bump version

The version must be updated to X.Y.Z in the release branch. There are multiple Cargo.toml and Cargo.lock files that need to be updated.

First, we need to update the version of the workspace package. You can find it in the Cargo.toml file in the root directory, under the [workspace.package] section.

Then, we need to update three more Cargo.toml files that are not part of the workspace but fulfill the role of packages in the monorepo. These are located in the following paths:

• crates/l2/prover/src/guest_program/src/sp1/Cargo.toml
• crates/l2/prover/src/guest_program/src/risc0/Cargo.toml
• crates/l2/tee/quote-gen/Cargo.toml

After updating the version in the Cargo.toml files, we need to update the Cargo.lock files to reflect the new versions. Run cargo tree in their respective directories:

• In the root directory
• crates/l2/prover/src/guest_program/src/sp1
• crates/l2/prover/src/guest_program/src/risc0
• crates/l2/tee/quote-gen

Then, go to the CLI.md file located in docs/ and update the version of the --builder.extra-data flag default value to match the new version (for both ethrex and ethrex l2 sections).

Finally, stage and commit the changes to the release branch.

An example of a PR that bumps the version can be found here.

3rd - Create & Push Tag

Create a tag with a format vX.Y.Z-rc.W where X.Y.Z is the semantic version and W is a release candidate version. Other names for subversions are also accepted. Example of valid tags:

• v0.1.3-rc.1
• v0.0.2-alpha

git tag <release_version>
git push origin <release_version>

After pushing the tag, a CI job will compile the binaries for different architectures and create a pre-release with the version specified in the tag name. Along with the binaries, a tar file is uploaded with the contracts and the verification keys. The following binaries are built:

Also, two docker images are built and pushed to the Github Container registry:

• ghcr.io/lambdaclass/ethrex:X.Y.Z-rc.W
• ghcr.io/lambdaclass/ethrex:X.Y.Z-rc.W-l2

A changelog will be generated based on commit names (using conventional commits) from the last stable tag.

4th - Test & Publish Release

When you are sure all the binaries and docker images work as expected, you can proceed to publish the release. To do so, edit the last pre-release with the following changes:

• Change the name to ethrex: vX.Y.Z
• Change the tag to a new one vX.Y.Z. IMPORTANT: Make sure to select the release/vX.Y.Z branch when changing the tag.
• Set the release as the latest release (you will need to uncheck the pre-release first).

Once done, the CI will publish new tags for the already compiled docker images:

• ghcr.io/lambdaclass/ethrex:X.Y.Z, ghcr.io/lambdaclass/ethrex:latest
• ghcr.io/lambdaclass/ethrex:X.Y.Z-l2, ghcr.io/lambdaclass/ethrex:l2

5th - Update Homebrew

Disclaimer: We should automate this

1. Commit a change in https://github.com/lambdaclass/homebrew-tap/ bumping the ethrex version (like this one).

   • The first SHA is the hash of the .tar.gz from the release. You can get it by downloading the Source code (tar.gz) from the ethrex release and running

     shasum -a 256 ethrex-v3.0.0.tar.gz
     

   • For the second one:

     • First download the ethrex-l2-macos-aarch64 binary from the ethrex release

     • Give exec permissions to binary

       chmod +x ethrex-l2-macos-aarch64
       

     • Create a dir ethrex/3.0.0/bin (replace the version as needed)

     • Move (and rename) the binary to ethrex/3.0.0/bin/ethrex (the last ethrex is the binary)

     • Remove quarantine flags (in this case, ethrex is the root dir mentioned before):

       xattr -dr com.apple.metadata:kMDItemWhereFroms ethrex
       xattr -dr com.apple.quarantine ethrex
       

     • Tar the dir with the following name (again, ethrex is the root dir):

       tar -czf ethrex-3.0.0.arm64_sonoma.bottle.tar.gz ethrex
       

     • Get the checksum:

       shasum -a 256 ethrex-3.0.0.arm64_sonoma.bottle.tar.gz
       

     • Use this as the second hash (the one in the bottle section)

2. Push the commit
3. Create a new release with tag v3.0.0. IMPORTANT: attach the ethrex-3.0.0.arm64_sonoma.bottle.tar.gz to the release

6th - Merge the release branch via PR

Once the release is verified, merge the branch via PR.

Dealing with hotfixes

If hotfixes are needed before the final release, commit them to release/vX.Y.Z, push, and create a new pre-release tag. The final tag vX.Y.Z should always point to the exact commit you will merge via PR.