Release Procedure¶

Table of contents¶

Introduction
Open a Release Pull Request
Bump the Version
Pick a Release Name
Generate Reference Tests
Install Git Large File Storage
Prepare Tests Repository
Commit Reference Tests
Bundle Reference Tests
Merge the Release Pull Request
Create Tests Release
Create Specs Release
Click the Release Buttons
Make an Announcement

Introduction¶

This document describes the necessary steps to produce a consensus-specs release.

Open a Release Pull Request¶

[!NOTE] Try to do this at least a few days prior to the release.

First, create a PR which merges dev into master.

[!TIP] Click on the following link to draft a PR: * https://github.com/ethereum/consensus-specs/compare/dev...master?expand=1

Title this PR "Release <version>" (e.g., "Release v1.5.0-alpha.10").

In the PR's description, provide a list of items that must be done. At the bottom, list unmerged PRs which are to be included in the release; this signals to other maintainers and developers that they should review these PRs soon.

- [ ] testgen
- [ ] version bump
- [ ] #1234
- [ ] #2345
- [ ] #3456

Bump the Version¶

Next, update the VERSION.txt file which contains the eth2spec version.

[!TIP] Click on the following link to open the GitHub editor for this file: * https://github.com/ethereum/consensus-specs/edit/dev/tests/core/pyspec/eth2spec/VERSION.txt

Next, change the version to the appropriate value and click the "Commit changes..." button.

For the commit message, put "Bump version to <version>" (e.g., "Bump version to 1.5.0-alpha.10").

Next, click the "Propose changes" button and proceed to make the PR.

Pick a Release Name¶

Generally, names are based on some theme. For example, for Electra, releases are named after Electric-type Pokemon.

[!NOTE] Please ensure that the name you choose does not have an unwanted meaning in other languages; use WordSafety.com to check this.

Generate Reference Tests¶

Install Git Large File Storage¶

The consensus-spec-tests repository uses Git LFS because it contains many large files. Attempt to install LFS support with the following command. If it does not work, please refer to the installation directions on their website.

1	`git lfs install`

Prepare Tests Repository¶

Next, clone the consensus-spec-tests repository.

[!NOTE] Only the single latest commit is needed to make the release. Use --depth=1 to do this. Please note that even this may take some time to checkout, as the combined size of the test vectors is multiple gigabytes.

1 2	`git clone https://github.com/ethereum/consensus-spec-tests.git --depth=1 cd consensus-spec-tests`

Next, remove directories which will be overwritten.

1	`rm -rf configs presets tests`

Commit Reference Tests¶

Next, change directory to outside of the tests repository.

cd ..

Next, clone the consensus-specs repository.

1 2	`git clone https://github.com/ethereum/consensus-specs.git cd consensus-specs`

Next, copy the presets and configuration files to the tests repository.

1 2	`cp -r presets ../consensus-spec-tests cp -r configs ../consensus-spec-tests`

Next, use make gen_all to generate all the reference tests. The following command will run all generators in parallel for maximum speed. The console output is saved to a file so we can check for errors afterwards.

[!TIP] Instead of this, another option is to use the test vectors that are automatically generated each night. To download these files, click the following link, then click the latest action run, and then download all of the artifacts. Please note, if there has been a change to the dev branch after the test vectors were generated, you can manually trigger the action with the "Run workflow" button.

https://github.com/ethereum/consensus-specs/actions/workflows/generate_vectors.yml

After downloading these artifacts, move them to the consensus-spec-tests directory. Then unzip each, then untar each of the *.tar.gz files. Use unzip <file>.zip and tar -xvf <file>.tar.gz to do this. Note that the "Bundle Reference Tests" section can be skipped if this route is taken.

1	`make --jobs gen_all 2>&1 \| tee ../consensustestgen.log`

Next, check for errors by searching for "ERROR" in test logfile.

1	`grep "ERROR" ../consensustestgen.log`

[!WARNING] If there is an error: (1) determine what the issue is, (2) create/merge a PR to fix the issue, and (3) restart the release process.

Next, change directory to the consensus-spec-tests repository:

1	`cd ../consensus-spec-tests`

Next, check that the differences look sane; that there are no unexpected changes. Sometimes there are several hundred (if not more) changes per release so use your best judgement when reviewing. One might ensure that there are no changes to old forks and double check a few reference tests to ensure they were indeed modified in this release.

1	`git lfs status`

Next, after reviewing the changes and are reasonably confident that they are okay, stage the changes.

1	`git add .`

Next, commit the changes.

[!IMPORTANT] Commits to consensus-spec-tests must be signed. Please refer to Signing Commits for instructions on setting this up.

1	`git commit --gpg-sign --message "release <version> tests"`

Finally, push the changes.

1	`git push origin master`

Bundle Reference Tests¶

Next, delete all empty directories.

1	`find . -type d -empty -delete`

Finally, tar each group of tests into separate tarballs.

1
2
3

tar -czvf general.tar.gz tests/general
tar -czvf minimal.tar.gz tests/minimal
tar -czvf mainnet.tar.gz tests/mainnet

Merge the Release Pull Request¶

After successfully generating the test vectors, we have confidence that the release is fine. We can now merge the release pull request which brings changes from the development branch into the master branch. Releases are made from the master branch.

Create Tests Release¶

First, begin to draft a new consensus-spec-tests release.

[!TIP] Click on the following link to draft a new release: * https://github.com/ethereum/consensus-spec-tests/releases/new

Next, click the "Choose a tag" button to create a new tag. Type in the release version (e.g., "v1.5.0-alpha.10") and click the "Create new tag: <version> on publish" button.

Next, provide a title "Spec tests for <version>" (e.g., "Spec tests for v1.5.0-alpha.10").

Next, provide a description. Use the following template:

1
2
3

Spec tests for <version>.

Detailed changelog can be found in [<version> specs release](https://github.com/ethereum/consensus-specs/releases/tag/<version>).

Next, upload the tarballs from the Bundle Reference Tests section to the release.

[!NOTE] This is expected to take a while if your upload speed is below average. The tarballs are at least 1 gigabyte in total. There is a progress bar shown for each artifact.

Next, if this is an alpha/beta release, please select the "Set as a pre-release" checkbox, otherwise select the "Set as the latest release" checkbox.

[!IMPORTANT] Do no click the release button just yet.

Create Specs Release¶

First, begin to draft a new consensus-specs release.

[!TIP] Click on the following link to draft a new release: * https://github.com/ethereum/consensus-specs/releases/new

Next, click the "Choose a tag" button to create a new tag. Type in the release version (e.g., "v1.5.0-alpha.10") and click the "Create new tag: <version> on publish" button.

Next, change the target from dev to master.

[!IMPORTANT] Do not forget this to change the target branch.

Next, provide a title "<release-name>" (e.g., "Bellibolt").

Next, provide a description. Use the following template:

<version> -- <release-name> -- <short-release-description>

_PR showing full diff can be found here: <this-PR-number>_

## <component-a>

* Add new feature #1234
* Fix problem in old feature #2345

## <component-b>

* Fix bug related to feature #3456

## Testing, repo, etc

* Add new test for feature #4567
* Improve documentation #5678

If this is an alpha/beta release, please select the "Set as a pre-release" checkbox, otherwise select the "Set as the latest release" checkbox.

[!IMPORTANT] Do no click the release button just yet.

Click the Release Buttons¶

First, click the release button for consensus-specs.
Then, click the release button for consensus-spec-tests.

[!NOTE] It should be done in this order because the tests release references the specs release. Also, we wait to push these buttons at the same time so their time/date will be approximately the same.

Make an Announcement¶

[!IMPORTANT] In order to do this, you must be granted the appropriate access.

Finally, make an announcement to the Eth R&D server on Discord. This should be posted in the #announcements channel. This will notify client developers of the new release and they will begin to incorporate the new reference tests into their client.

Use the following template for your announcement:

Consensus layer specs <version> -- <release-name> -- released!

https://github.com/ethereum/consensus-specs/releases/tag/<version>

Test vectors: https://github.com/ethereum/consensus-spec-tests/releases/tag/<version>