chore(ci): address fixture release review feedback

Author: spencer-tb

.github/actions/build-evm-base/action.yaml

@@ -25,9 +25,9 @@ outputs:
   evm-bin:
     description: "Binary name of the evm tool to use"
     value: ${{ steps.config-evm-reader.outputs.evm-bin }}
-  x-dist:
+  xdist:
     description: "Number of parallel pytest-xdist workers to use"
-    value: ${{ steps.config-evm-reader.outputs.x-dist }}
+    value: ${{ steps.config-evm-reader.outputs.xdist }}
 runs:
   using: "composite"
   steps:
@@ -56,7 +56,7 @@ runs:
         echo "Repository: ${{ steps.resolved.outputs.repo }}"
         echo "Reference: ${{ steps.resolved.outputs.ref }}"
         echo "EVM Binary: ${{ steps.config-evm-reader.outputs.evm-bin }}"
-        echo "X-Dist parameter: ${{ steps.config-evm-reader.outputs.x-dist }}"
+        echo "X-Dist parameter: ${{ steps.config-evm-reader.outputs.xdist }}"
     - name: Skip building for EELS
       if: steps.config-evm-reader.outputs.impl == 'eels'
       shell: bash

.github/actions/build-fixtures/action.yaml

@@ -64,9 +64,9 @@ runs:
         # Allow exit code 5 (NO_TESTS_COLLECTED) for fork ranges with no tests.
         EXIT_CODE=0
         if [ "${{ steps.evm-builder.outputs.impl }}" = "eels" ]; then
-          uv run fill -n ${{ steps.evm-builder.outputs.x-dist }} ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} --no-html --durations=100 --log-level=DEBUG || EXIT_CODE=$?
+          uv run fill -n ${{ steps.evm-builder.outputs.xdist }} ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} --no-html --durations=100 --log-level=DEBUG || EXIT_CODE=$?
         else
-          uv run fill -n ${{ steps.evm-builder.outputs.x-dist }} --evm-bin=${{ steps.evm-builder.outputs.evm-bin }} ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} --no-html --durations=100 --log-level=DEBUG || EXIT_CODE=$?
+          uv run fill -n ${{ steps.evm-builder.outputs.xdist }} --evm-bin=${{ steps.evm-builder.outputs.evm-bin }} ${{ steps.properties.outputs.fill-params }} $FORK_ARGS $OUTPUT_ARG --build-name ${{ inputs.release_name }} --no-html --durations=100 --log-level=DEBUG || EXIT_CODE=$?
         fi
         if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 5 ]; then
           exit "$EXIT_CODE"

.github/configs/evm.yaml

@@ -1,39 +1,33 @@
-# Client aliases
+# `benchmark` is a client alias (resolves to geth) referenced by name in
+# .github/workflows/benchmark.yaml.
 benchmark:
   impl: geth
   repo: ethereum/go-ethereum
   ref: master
   evm-bin: evm
-  x-dist: auto
-consensus:
-  impl: eels
-  repo: null
-  ref: null
-  evm-bin: null
-  x-dist: auto
-
+  xdist: auto
 eels:
   impl: eels
   repo: null
   ref: null
   evm-bin: null
-  x-dist: auto
+  xdist: auto
 evmone:
   impl: evmone
   repo: ethereum/evmone
   ref: master
   targets: ["evmone-t8n"]
   evm-bin: evmone-t8n
-  x-dist: auto
+  xdist: auto
 geth:
   impl: geth
   repo: ethereum/go-ethereum
   ref: master
   evm-bin: evm
-  x-dist: auto
+  xdist: auto
 besu:
   impl: besu
   repo: hyperledger/besu
   ref: main
   evm-bin: evmtool
-  x-dist: 0
+  xdist: 0

.github/configs/feature.yaml

@@ -1,12 +1,29 @@
+# Release feature definitions consumed by the release_fixtures workflow.
+#
+# Each top-level key is either:
+#   1. A literal feature name used in the release tag, e.g. `benchmark` ->
+#      tag `tests-benchmark@vX.Y.Z`. The default `tests` feature tags as
+#      `tests@vX.Y.Z` directly (not `tests-tests@`).
+#   2. The shared `devnet` entry, which is resolved by `-devnet` suffix:
+#      any workflow input feature ending in `-devnet` (e.g. `bal-devnet`,
+#      `glamsterdam-devnet`) maps here while keeping its `<feat>-devnet`
+#      name in the tag (`tests-<feat>-devnet@vX.Y.Z`). The devnet index
+#      is encoded in the version (X), not in the feature name -- so
+#      `glamsterdam-devnet-5` (branch) releases as feature
+#      `glamsterdam-devnet` at version `v5.0.0`, yielding the tag
+#      `tests-glamsterdam-devnet@v5.0.0`. This means `feature.yaml` does
+#      not need to be updated for new devnets.
+#
 # Unless filling for special features, all features should fill for previous forks (starting from Frontier) too
-consensus:
-  evm-type: consensus
-  fill-params: --until=BPO4
+tests:
+  evm-type: eels
+  fill-params: --until=BPO4 --generate-all-formats
 
 benchmark:
   evm-type: benchmark
   fill-params: --fork=Amsterdam --gas-benchmark-values 1,10,30,60,100,150 ./tests/benchmark
 
+# Shared entry for all `<feat>-devnet` releases; matched by `-devnet` suffix.
 devnet:
   evm-type: eels
-  fill-params: --until=Amsterdam
+  fill-params: --until=Amsterdam --generate-all-formats

.github/scripts/generate_build_matrix.py

@@ -21,12 +21,15 @@
 import re
 import sys
 from pathlib import Path
+from typing import NoReturn
 
 import yaml
 
 FEATURE_CONFIG = Path(".github/configs/feature.yaml")
 FORK_RANGES_CONFIG = Path(".github/configs/fork-ranges.yaml")
 
+VERSION_RE = re.compile(r"^v[0-9]+\.[0-9]+\.[0-9]+$")
+
 # Canonical fork ordering used to filter fork ranges per feature.
 FORK_ORDER = [
     "Frontier",
@@ -64,6 +67,65 @@ def load_config(path: Path) -> dict:
         return yaml.safe_load(f)
 
 
+def fail(message: str) -> NoReturn:
+    """Print an error to stderr and exit non-zero."""
+    print(f"Error: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+def validate_inputs(feature: str, version: str, branch: str) -> None:
+    """
+    Validate the release dispatch inputs before building a matrix.
+
+    Centralize the feature/version checks here so they are unit-testable
+    rather than living as inline bash in the release workflow.
+
+    For ``<feat>-devnet`` releases the major version (``X`` of ``vX.Y.Z``)
+    must equal the devnet number encoded in the release branch, so a
+    ``bal-devnet`` release from ``bal-devnet-7`` must be tagged ``v7.*.*``.
+    """
+    if not feature:
+        fail("feature name is empty")
+    if not VERSION_RE.match(version):
+        fail(f"version '{version}' must match vX.Y.Z (e.g. v20.0.0)")
+
+    # A bare `devnet` has no friendly `<feat>-` prefix to tag with.
+    if feature in ("devnet", "-devnet"):
+        fail("devnet releases require a <feat>- prefix, e.g. bal-devnet")
+
+    # `<feat>-devnet-<n>`: the devnet index belongs in the version (X of
+    # vX.Y.Z), not in the feature name.
+    if "-devnet-" in feature:
+        suggested_feature, _, suggested_index = feature.rpartition("-")
+        fail(
+            "devnet index must go in 'version', not the feature name; "
+            f"did you mean feature={suggested_feature} "
+            f"version=v{suggested_index}.0.0?"
+        )
+
+    if feature.endswith("-devnet"):
+        if not branch:
+            fail(
+                "devnet releases require a 'branch' input, "
+                "e.g. branch=bal-devnet-7"
+            )
+        match = re.search(r"(\d+)$", branch)
+        if not match:
+            fail(
+                f"could not parse a devnet number from branch '{branch}' "
+                "(expected a trailing number, e.g. bal-devnet-7)"
+            )
+        devnet_number = int(match.group(1))
+        major = int(version.lstrip("v").split(".")[0])
+        if major != devnet_number:
+            minor_patch = version.split(".", 1)[1]
+            fail(
+                f"version major (v{major}) must equal the devnet number "
+                f"({devnet_number}) from branch '{branch}'; "
+                f"did you mean version=v{devnet_number}.{minor_patch}?"
+            )
+
+
 def parse_until_fork(fill_params: str) -> str | None:
     """
     Extract the ``--until`` value from fill-params.
@@ -134,16 +196,22 @@ def build_matrix(
 
 def main() -> None:
     """Entry point."""
-    if len(sys.argv) != 2:
+    args = sys.argv[1:]
+    if len(args) < 2:
         print(
-            "Usage: generate_build_matrix.py <feature>",
+            "Usage: generate_build_matrix.py <feature> <version> [branch]",
             file=sys.stderr,
         )
         sys.exit(1)
 
+    name = args[0]
+    version = args[1]
+    branch = args[2] if len(args) > 2 else ""
+
+    validate_inputs(name, version, branch)
+
     config = load_config(FEATURE_CONFIG)
     fork_ranges = load_config(FORK_RANGES_CONFIG) or []
-    name = sys.argv[1]
 
     # `<feat>-devnet` releases (e.g. bal-devnet) share the `devnet` entry,
     # while keeping their friendly name in the matrix and artifact outputs.

.github/scripts/tests/test_release_scripts.py

@@ -43,12 +43,12 @@ class TestGenerateBuildMatrix:
 
     def test_split_feature_produces_entries_per_range(self):
         """Verify a split feature expands into one entry per range."""
-        result = run_script(BUILD_MATRIX_SCRIPT, "consensus")
+        result = run_script(BUILD_MATRIX_SCRIPT, "tests", "v24.0.0")
         assert result.returncode == 0
         out = parse_matrix_output(result.stdout)
         matrix = json.loads(out["build_matrix"])
         assert len(matrix) > 1
-        assert out["feature_name"] == "consensus"
+        assert out["feature_name"] == "tests"
         assert out["combine_labels"] != ""
         labels = [e["label"] for e in matrix]
         assert all(lbl != "" for lbl in labels)
@@ -57,7 +57,7 @@ def test_split_feature_produces_entries_per_range(self):
 
     def test_unsplit_feature_produces_single_entry(self):
         """Verify a feature without fork-ranges produces one entry."""
-        result = run_script(BUILD_MATRIX_SCRIPT, "benchmark")
+        result = run_script(BUILD_MATRIX_SCRIPT, "benchmark", "v24.0.0")
         assert result.returncode == 0
         out = parse_matrix_output(result.stdout)
         matrix = json.loads(out["build_matrix"])
@@ -70,7 +70,9 @@ def test_unsplit_feature_produces_single_entry(self):
 
     def test_devnet_name_resolves_to_shared_feature(self):
         """Verify a <feat>-devnet name resolves to the devnet feature."""
-        result = run_script(BUILD_MATRIX_SCRIPT, "bal-devnet")
+        result = run_script(
+            BUILD_MATRIX_SCRIPT, "bal-devnet", "v7.0.0", "bal-devnet-7"
+        )
         assert result.returncode == 0
         out = parse_matrix_output(result.stdout)
         matrix = json.loads(out["build_matrix"])
@@ -80,7 +82,7 @@ def test_devnet_name_resolves_to_shared_feature(self):
 
     def test_unknown_feature_fails(self):
         """Verify error exit for unknown feature name."""
-        result = run_script(BUILD_MATRIX_SCRIPT, "nonexistent")
+        result = run_script(BUILD_MATRIX_SCRIPT, "nonexistent", "v1.0.0")
         assert result.returncode == 1
         assert "not found" in result.stderr
 
@@ -92,7 +94,7 @@ def test_no_args_fails(self):
 
     def test_output_is_valid_github_actions_format(self):
         """Verify output lines are key=value for GITHUB_OUTPUT."""
-        result = run_script(BUILD_MATRIX_SCRIPT, "consensus")
+        result = run_script(BUILD_MATRIX_SCRIPT, "tests", "v24.0.0")
         assert result.returncode == 0
         lines = result.stdout.strip().splitlines()
         assert len(lines) == 3
@@ -101,6 +103,57 @@ def test_output_is_valid_github_actions_format(self):
         assert lines[2].startswith("combine_labels=")
 
 
+class TestValidateInputs:
+    """Test the release input validation in generate_build_matrix.py."""
+
+    def test_bad_version_fails(self):
+        """Verify a non vX.Y.Z version is rejected."""
+        result = run_script(BUILD_MATRIX_SCRIPT, "tests", "24.0.0")
+        assert result.returncode == 1
+        assert "must match vX.Y.Z" in result.stderr
+
+    def test_bare_devnet_fails(self):
+        """Verify a bare `devnet` feature name is rejected."""
+        result = run_script(
+            BUILD_MATRIX_SCRIPT, "devnet", "v7.0.0", "bal-devnet-7"
+        )
+        assert result.returncode == 1
+        assert "require a <feat>- prefix" in result.stderr
+
+    def test_devnet_index_in_feature_name_fails(self):
+        """Verify `<feat>-devnet-<n>` is rejected with a suggestion."""
+        result = run_script(
+            BUILD_MATRIX_SCRIPT, "bal-devnet-7", "v7.0.0", "bal-devnet-7"
+        )
+        assert result.returncode == 1
+        assert "did you mean feature=bal-devnet version=v7.0.0" in (
+            result.stderr
+        )
+
+    def test_devnet_without_branch_fails(self):
+        """Verify a `<feat>-devnet` release requires a branch."""
+        result = run_script(BUILD_MATRIX_SCRIPT, "bal-devnet", "v7.0.0")
+        assert result.returncode == 1
+        assert "require a 'branch' input" in result.stderr
+
+    def test_devnet_major_must_match_branch_number(self):
+        """Verify the major version must equal the branch devnet number."""
+        result = run_script(
+            BUILD_MATRIX_SCRIPT, "bal-devnet", "v3.0.0", "bal-devnet-7"
+        )
+        assert result.returncode == 1
+        assert "must equal the devnet number" in result.stderr
+
+    def test_devnet_matching_major_passes(self):
+        """Verify a matching major/branch number builds the matrix."""
+        result = run_script(
+            BUILD_MATRIX_SCRIPT, "bal-devnet", "v7.0.0", "bal-devnet-7"
+        )
+        assert result.returncode == 0
+        out = parse_matrix_output(result.stdout)
+        assert out["feature_name"] == "bal-devnet"
+
+
 class TestCreateReleaseTarball:
     """Test create_release_tarball.py."""