From 72bd744c658343a282c056269e67f8c645ec8beb Mon Sep 17 00:00:00 2001 From: danceratopz Date: Mon, 1 Sep 2025 15:10:33 +0200 Subject: [PATCH 1/9] docs: update CONTRIBUTING.md for `uv` and `ruff` --- CONTRIBUTING.md | 98 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 79 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5cb1e62462..7106c1ca11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,50 +41,110 @@ This saves you having to apply code review feedback repeatedly for each fork. Running the tests necessary to merge into the repository requires: - * Python 3.11.x, and - * [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later. + * Python 3.11.x, + * [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later + * [`uv`](https://docs.astral.sh/uv/) package manager * `geth` installed and present in `$PATH` +`uv` can be installed via curl (recommended; can self-update): + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +or pip (requires Python, can't self-update): + +```bash +pip install uv +``` + `execution-specs` depends on a submodule that contains common tests that are run across all clients, so we need to clone the repo with the --recursive flag. Example: ```bash -$ git clone --recursive https://github.com/ethereum/execution-specs.git +git clone --recursive https://github.com/ethereum/execution-specs.git +cd execution-specs ``` Or, if you've already cloned the repository, you can fetch the submodules with: ```bash -$ git submodule update --init --recursive +git submodule update --init --recursive +``` + +Set up your development environment: + +```bash +uv python install 3.11 +uv python pin 3.11 +uv sync --all-extras ``` The tests can be run with: ```bash -$ tox +uvx --with=tox-uv tox ``` -The development tools can also be run outside of `tox`, and can automatically reformat the code: +The development tools can also be run directly with `uv`, which handles the virtual environment automatically: ```bash -$ pip install -e ".[doc,lint,test,fill]" # Installs ethereum, and development tools. -$ isort src # Organizes imports. -$ black src # Formats code. -$ flake8 # Reports style/spelling/documentation errors. -$ mypy src # Verifies type annotations. -$ pytest -n 4 # Runs tests parallelly. -$ pytest -m "not slow" # Runs tests which execute quickly. +uv run ruff check src --fix # Check and fix linting issues, format code, organize imports +uv run ruff format src # Format code (similar to black) +uv run codespell -I whitelist.txt src # Check spelling +uv run mypy src --namespace-packages # Verify type annotations +uv run pytest -n 4 # Run tests in parallel +uv run pytest -m "not slow" # Run tests which execute quickly ``` -It is recommended to use a [virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) to keep your system Python installation clean. +The repository includes several tox environments for different testing scenarios: + +- `static` - Linting, type checking, spell checking, and documentation build. +- `json_infra` - Tests for the JSON infrastructure. +- `py3` - Run execution spec tests using CPython. +- `pypy3` - Run execution spec tests using PyPy. + +You can run specific tox environments individually, e,g: + +```bash +uvx --with=tox-uv tox -e static # Run linting and type checking. +``` + +Or run all environments in parallel: + +```bash +uvx --with=tox-uv tox run-parallel +``` + +The specification tests can also be ran directly: + +```bash +uv run ethereum-spec-fill tests/eest --clean --until Osaka +``` A trace of the EVM execution for any test case can be obtained by providing the `--evm-trace` argument to pytest. Note: Make sure to run the EVM trace on a small number of tests at a time. The log might otherwise get very big. Below is an example. ```bash -pytest tests/frontier/test_state_transition.py -k 'test_general_state_tests_new' --evm-trace +uv run pytest tests/frontier/test_state_transition.py -k 'test_general_state_tests_new' --evm-trace ``` +## Code Standards + +The codebase follows specific formatting and linting standards enforced by `ruff`, which replaces `black`, `isort`, and `flake8`: + +- **Line Length**: 79 characters maximum. +- **Formatting**: Enforced by `ruff format` (similar to `black`). +- **Import Sorting**: Handled by `ruff check` (similar to `isort`). +- **Linting**: Code quality checks via `ruff check`. +- **Type Checking**: Enforced by `mypy` for type annotations. +- **Spell Checking**: Documentation and comments checked by `codespell` + +All these standards are automatically checked in CI via the `static` tox environment. You can run the checks locally: + +```bash +uvx --with=tox-uv tox -e static +``` ## CLI Utilities `ethereum_spec_tools` @@ -103,7 +163,7 @@ The command takes 4 arguments, 2 of which are optional As an example, if one wants to create baseline code for the `Spurious Dragon` fork from the `Tangerine Whistle` one ```bash -ethereum-spec-new-fork --from_fork="Tangerine Whistle" --to_fork="Spurious Dragon" --from_test=EIP150 --to_test=EIP158 +uv run ethereum-spec-new-fork --from_fork="Tangerine Whistle" --to_fork="Spurious Dragon" --from_test=EIP150 --to_test=EIP158 ``` The following will have to however, be updated manually @@ -122,7 +182,7 @@ very slow, one can also leverage the optimized module. This contains alternative in EELS that have been optimized for speed rather than clarity/readability. -The tool can be called using the `ethereum-spec-sync` command which takes the following arguments +The tool can be called using the `uv run ethereum-spec-sync` command which takes the following arguments * rpc-url: Endpoint providing the Ethereum RPC API. Defaults to `http://localhost:8545/` * unoptimized: Don't use the optimized state/ethash (this can be extremely slow) * persist: Store the state in a db in this file @@ -151,7 +211,7 @@ The tool takes the following command line arguments As an example, if one wants to apply changes made in `Frontier` fork to `Homestead` and `Tangerine Whistle` ```bash -python src/ethereum_spec_tools/patch_tool.py frontier homestead tangerine_whistle +uv run ethereum-spec-patch frontier homestead tangerine_whistle ``` ### Lint Tool @@ -163,4 +223,4 @@ The tool currently performs the following checks - The order of the identifiers between each hardfork is consistent. - Import statements follow the relevant import rules in modules. -The command to run the tool is `ethereum-spec-lint` +The command to run the tool is `uv run ethereum-spec-lint` From 006d0f6171663330b55a66aa4d61836ad6d2fd9a Mon Sep 17 00:00:00 2001 From: danceratopz Date: Mon, 1 Sep 2025 16:40:10 +0200 Subject: [PATCH 2/9] chore: remove empty/unused .gitmodules file --- .gitmodules | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .gitmodules diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index e69de29bb2..0000000000 From c52604ca91ba1b9ea8a89196ae810e8859095fcb Mon Sep 17 00:00:00 2001 From: danceratopz Date: Mon, 1 Sep 2025 16:46:34 +0200 Subject: [PATCH 3/9] docs: remove out-of-date git submodule docs from contributing --- CONTRIBUTING.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7106c1ca11..ee286ee4a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,21 +59,11 @@ or pip (requires Python, can't self-update): pip install uv ``` -`execution-specs` depends on a submodule that contains common tests that are run across all clients, so we need to clone the repo with the --recursive flag. Example: -```bash -git clone --recursive https://github.com/ethereum/execution-specs.git -cd execution-specs -``` - -Or, if you've already cloned the repository, you can fetch the submodules with: - -```bash -git submodule update --init --recursive -``` - -Set up your development environment: +Clone the repository and set up your development environment: ```bash +git clone https://github.com/ethereum/execution-specs.git +cd execution-specs uv python install 3.11 uv python pin 3.11 uv sync --all-extras From 42bc27216817fe738c82281721eb6848329ac610 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Mon, 1 Sep 2025 16:46:58 +0200 Subject: [PATCH 4/9] docs: add a section explaining current state of the weld --- CONTRIBUTING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ee286ee4a1..f99524286e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -136,6 +136,23 @@ All these standards are automatically checked in CI via the `static` tox environ uvx --with=tox-uv tox -e static ``` +## Integration with execution-spec-tests + +**Note: This integration is a work in progress (WIP).** + +The execution-specs repository has integrated code from the [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repository using git subtrees. This integration includes: + +- **`src/ethereum_spec_tests/`** - The test framework, CLI tools, and utilities from execution-spec-tests, +- **`tests/eest/`** - The actual EVM test cases from execution-spec-tests. + +### Important: Read-Only Subtree Directories + +The subtree directories (`src/ethereum_spec_tests/` and `tests/eest/`) should be treated as **read-only** in this repository. Any changes to code in these directories should be made via pull requests to the upstream [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repository, not directly in execution-specs. + +If you need to modify test framework code or test cases, please: +1. Fork and submit PRs to [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests). +2. Once merged upstream, the subtrees in execution-specs will be updated accordingly. + ## CLI Utilities `ethereum_spec_tools` The EELS repository has various CLI utilities that can help in the development process. From aba22391d8411e507dd6c07f716574917f60cf87 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Tue, 2 Sep 2025 11:47:39 +0200 Subject: [PATCH 5/9] docs: second pass at contributing; correct commands --- CONTRIBUTING.md | 126 ++++++++++++++++++++++++------------------------ 1 file changed, 62 insertions(+), 64 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f99524286e..3a41c3d0c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,14 +4,12 @@ Help is always welcome and there are plenty of options to contribute to the Ethe In particular, we appreciate support in the following areas: -- Reporting issues +- Reporting issues. - Fixing and responding to [issues](https://github.com/ethereum/execution-specs/issues), especially those tagged as [E-easy](https://github.com/ethereum/execution-specs/labels/E-easy) which are meant as introductory issues for external contributors. - Improving the documentation. - For details about EELS usage and building, please refer the [README](https://github.com/ethereum/execution-specs/blob/master/README.md#usage) - ## Contribution Guidelines This specification aims to be: @@ -24,7 +22,7 @@ This specification aims to be: - Attempt to use descriptive English words (or _very common_ abbreviations) in documentation and identifiers. - Avoid using EIP numbers in identifiers. -- If necessary, there is a custom dictionary `whitelist.txt`. +- If necessary, there is a custom dictionary `whitelist.txt`. ### Changes across various Forks @@ -36,16 +34,15 @@ When creating pull requests affecting multiple forks, we recommended submitting 2. Apply the changes across the other forks, push them, and mark the pull request as ready for review. This saves you having to apply code review feedback repeatedly for each fork. - + ### Development Running the tests necessary to merge into the repository requires: - * Python 3.11.x, - * [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later - * [`uv`](https://docs.astral.sh/uv/) package manager - * `geth` installed and present in `$PATH` - +- Python 3.11.x, +- [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later +- [`uv`](https://docs.astral.sh/uv/) package manager +- `geth` installed and present in `$PATH` `uv` can be installed via curl (recommended; can self-update): @@ -69,49 +66,52 @@ uv python pin 3.11 uv sync --all-extras ``` -The tests can be run with: -```bash -uvx --with=tox-uv tox -``` - -The development tools can also be run directly with `uv`, which handles the virtual environment automatically: +All tests, as executed in CI, can be run with (very slow): ```bash -uv run ruff check src --fix # Check and fix linting issues, format code, organize imports -uv run ruff format src # Format code (similar to black) -uv run codespell -I whitelist.txt src # Check spelling -uv run mypy src --namespace-packages # Verify type annotations -uv run pytest -n 4 # Run tests in parallel -uv run pytest -m "not slow" # Run tests which execute quickly +uvx --with=tox-uv tox ``` - The repository includes several tox environments for different testing scenarios: - `static` - Linting, type checking, spell checking, and documentation build. -- `json_infra` - Tests for the JSON infrastructure. -- `py3` - Run execution spec tests using CPython. -- `pypy3` - Run execution spec tests using PyPy. +- `json_infra` - Run specific execution spec test releases. +- `py3` - Run the local version of execution spec tests using CPython. +- `pypy3` - Run the local version of execution spec tests using PyPy. -You can run specific tox environments individually, e,g: +It is recommended to run the `static` checks locally before pushing changes to a pull request: ```bash -uvx --with=tox-uv tox -e static # Run linting and type checking. +tox -e static # Run linting and type checking. ``` -Or run all environments in parallel: +All environments in parallel (very slow, even in parallel): ```bash -uvx --with=tox-uv tox run-parallel +tox run-parallel ``` -The specification tests can also be ran directly: +#### Development Tools + +The development tools can also be run directly with `uv`, which handles the virtual environment automatically: + +```bash +uv run codespell -I whitelist.txt {tox_root}/src --skip '{tox_root}/src/ethereum_spec_tests' # Spellcheck source +uv run ruff check src --exclude src/ethereum_spec_tests # Linting +uv run mypy src --exclude "src/ethereum_spec_tests/*" --namespace-packages # Static type checking +``` + +#### EEST / Spec-Tests + +A subset of the spec-tests (specified via a substring match to `-k`) can be run directly via: ```bash -uv run ethereum-spec-fill tests/eest --clean --until Osaka +uv run ethereum-spec-fill tests/eest --clean --fork Osaka -k eip7939 ``` -A trace of the EVM execution for any test case can be obtained by providing the `--evm-trace` argument to pytest. +#### Spec Unit Tests + +A trace of the EVM execution for any unit test case can be obtained by providing the `--evm-trace` argument to pytest. Note: Make sure to run the EVM trace on a small number of tests at a time. The log might otherwise get very big. Below is an example. @@ -121,20 +121,16 @@ uv run pytest tests/frontier/test_state_transition.py -k 'test_general_state_tes ## Code Standards -The codebase follows specific formatting and linting standards enforced by `ruff`, which replaces `black`, `isort`, and `flake8`: +The codebase follows specific formatting and linting standards enforced by `ruff` (which combines similar functionality to that of `black`, `isort`, and `flake8`): - **Line Length**: 79 characters maximum. - **Formatting**: Enforced by `ruff format` (similar to `black`). - **Import Sorting**: Handled by `ruff check` (similar to `isort`). - **Linting**: Code quality checks via `ruff check`. - **Type Checking**: Enforced by `mypy` for type annotations. -- **Spell Checking**: Documentation and comments checked by `codespell` +- **Spell Checking**: Documentation and comments checked by `codespell`. -All these standards are automatically checked in CI via the `static` tox environment. You can run the checks locally: - -```bash -uvx --with=tox-uv tox -e static -``` +All these standards are automatically checked in CI via the `static` tox environment (see above). ## Integration with execution-spec-tests @@ -150,6 +146,7 @@ The execution-specs repository has integrated code from the [ethereum/execution- The subtree directories (`src/ethereum_spec_tests/` and `tests/eest/`) should be treated as **read-only** in this repository. Any changes to code in these directories should be made via pull requests to the upstream [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repository, not directly in execution-specs. If you need to modify test framework code or test cases, please: + 1. Fork and submit PRs to [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests). 2. Once merged upstream, the subtrees in execution-specs will be updated accordingly. @@ -158,14 +155,15 @@ If you need to modify test framework code or test cases, please: The EELS repository has various CLI utilities that can help in the development process. ### New Fork Tool ------------------ + This tool can be used to create the base code for a new fork by using the existing code from a given fork. The command takes 4 arguments, 2 of which are optional - * from_fork: The fork name from which the code is to be duplicated. Eg. - "Tangerine Whistle" - * to_fork: The fork name of the new fork Eg - "Spurious Dragon" - * from_test (Optional): Name of the from fork within the test fixtures in case it is different from fork name. Eg. - "EIP150" - * to_test (Optional): Name of the to fork within the test fixtures in case it is different from fork name Eg - "EIP158" + +- from_fork: The fork name from which the code is to be duplicated. Eg. - "Tangerine Whistle" +- to_fork: The fork name of the new fork Eg - "Spurious Dragon" +- from_test (Optional): Name of the from fork within the test fixtures in case it is different from fork name. Eg. - "EIP150" +- to_test (Optional): Name of the to fork within the test fixtures in case it is different from fork name Eg - "EIP158" As an example, if one wants to create baseline code for the `Spurious Dragon` fork from the `Tangerine Whistle` one @@ -174,46 +172,45 @@ uv run ethereum-spec-new-fork --from_fork="Tangerine Whistle" --to_fork="Spuriou ``` The following will have to however, be updated manually + 1. The fork number and `MAINNET_FORK_BLOCK` in `__init__.py`. If you are proposing a new EIP, please set `MAINNET_FORK_BLOCK` to `None`. 2. Any absolute package imports from other forks eg. in `trie.py` 3. Package names under `setup.cfg` 4. Add the new fork to the `monkey_patch()` function in `src/ethereum_optimized/__init__.py` 5. Adjust the underline in `fork/__init__.py` - ### Sync Tool -------------- + The sync tool allows one to use an RPC provider to fetch and validate blocks against EELS. The state can also be stored in a local DB after validation. Since syncing directly with the specs can be very slow, one can also leverage the optimized module. This contains alternative implementations of routines in EELS that have been optimized for speed rather than clarity/readability. - The tool can be called using the `uv run ethereum-spec-sync` command which takes the following arguments - * rpc-url: Endpoint providing the Ethereum RPC API. Defaults to `http://localhost:8545/` - * unoptimized: Don't use the optimized state/ethash (this can be extremely slow) - * persist: Store the state in a db in this file - * geth: Use geth specific RPC endpoints while fetching blocks - * reset: Delete the db and start from scratch - * gas-per-commit: Commit to db each time this much gas is consumed. Defaults to 1_000_000_000 - * initial-state: Start from the state in this db, rather than genesis - * stop-at: After syncing this block, exit successfully + +- rpc-url: Endpoint providing the Ethereum RPC API. Defaults to `http://localhost:8545/` +- unoptimized: Don't use the optimized state/ethash (this can be extremely slow) +- persist: Store the state in a db in this file +- geth: Use geth specific RPC endpoints while fetching blocks +- reset: Delete the db and start from scratch +- gas-per-commit: Commit to db each time this much gas is consumed. Defaults to 1_000_000_000 +- initial-state: Start from the state in this db, rather than genesis +- stop-at: After syncing this block, exit successfully - The following options are not supported WITH `--unoptimized` -> `--persist`, `--initial-state`, `--reset` - The following options are not supported WITHOUT `--persist` -> `--initial_state`, `--reset` - ### Patch Tool --------------- + This tool can be used to apply the unstaged changes in `SOURCE_FORK` to each of the `TARGET_FORKS`. If some of the change didn't apply, '.rej' files listing the unapplied changes will be left in the `TARGET_FORK`. - The tool takes the following command line arguments - * The fork name where the changes have been made. Eg:- `frontier` (only a single fork name) - * The fork names where the changes have to be applied. Eg:- `homestead` (multiple values can be provided separated by space) - * optimized: Patch the optimized code instead - * tests: Patch the tests instead + +- The fork name where the changes have been made. Eg:- `frontier` (only a single fork name) +- The fork names where the changes have to be applied. Eg:- `homestead` (multiple values can be provided separated by space) +- optimized: Patch the optimized code instead +- tests: Patch the tests instead As an example, if one wants to apply changes made in `Frontier` fork to `Homestead` and `Tangerine Whistle` @@ -222,11 +219,12 @@ uv run ethereum-spec-patch frontier homestead tangerine_whistle ``` ### Lint Tool -------------- + This tool checks for style and formatting issues specific to EELS and emits diagnostics when issues are found The tool currently performs the following checks + - The order of the identifiers between each hardfork is consistent. - Import statements follow the relevant import rules in modules. From d07de8d11680d54acf5605830560006a65dec1a4 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Wed, 3 Sep 2025 07:30:56 +0200 Subject: [PATCH 6/9] Fix-up tox environment description via Guru's suggestion Co-authored-by: Guruprasad Kamath --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a41c3d0c5..d216c506da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,7 +74,7 @@ uvx --with=tox-uv tox The repository includes several tox environments for different testing scenarios: -- `static` - Linting, type checking, spell checking, and documentation build. +- `static` - Linting, type checking and spell checking. - `json_infra` - Run specific execution spec test releases. - `py3` - Run the local version of execution spec tests using CPython. - `pypy3` - Run the local version of execution spec tests using PyPy. From 980aa824891841b7e5b262b0b887cb9596bb247f Mon Sep 17 00:00:00 2001 From: danceratopz Date: Wed, 3 Sep 2025 07:31:57 +0200 Subject: [PATCH 7/9] Prefix `tox` with `uvx` to prevent depdendency problems --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d216c506da..c5abe470d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,7 +69,7 @@ uv sync --all-extras All tests, as executed in CI, can be run with (very slow): ```bash -uvx --with=tox-uv tox +uvx tox ``` The repository includes several tox environments for different testing scenarios: @@ -82,13 +82,13 @@ The repository includes several tox environments for different testing scenarios It is recommended to run the `static` checks locally before pushing changes to a pull request: ```bash -tox -e static # Run linting and type checking. +uvx tox -e static # Run linting and type checking. ``` All environments in parallel (very slow, even in parallel): ```bash -tox run-parallel +uvx tox run-parallel ``` #### Development Tools From 5ecd3448d58cd1dd506ece0d5563b00839fdcb78 Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 4 Sep 2025 14:23:15 +0200 Subject: [PATCH 8/9] Expand `uv` installation; running tox w/all envs not recommended --- CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5abe470d0..fab1687d32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,23 +39,42 @@ This saves you having to apply code review feedback repeatedly for each fork. Running the tests necessary to merge into the repository requires: +- [`uv`](https://docs.astral.sh/uv/) package manager, - Python 3.11.x, -- [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later -- [`uv`](https://docs.astral.sh/uv/) package manager +- [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later (typically only required by execution-specs maintainers), - `geth` installed and present in `$PATH` -`uv` can be installed via curl (recommended; can self-update): +#### Installing `uv` + +`uv` can be installed via `curl`, some package managers or `pip`. It is recommended to use `curl` or a package manager to enable easier updates (`curl`-installs can run `uv self update`) and install and manage Python installations. See `uv`'s [installation docs](https://docs.astral.sh/uv/getting-started/installation/) for package manager support and other information. ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` -or pip (requires Python, can't self-update): +#### Installing Python and PyPy with `uv` + +`uv` can be used to install the required version of Python, if not already available: + +```bash +uv python install 3.11 +uv python pin 3.11 +``` + +For [PyPy](ttps://www.pypy.org/) (this is typically only required by execution-specs maintainers): + +```bash +uv python install pypy-3.11.13-linux-x86_64-gnu +``` + +or pick the most recent PyPy 3.11 version from this list: ```bash -pip install uv +uv python list ``` +#### Development Setup + Clone the repository and set up your development environment: ```bash @@ -66,12 +85,6 @@ uv python pin 3.11 uv sync --all-extras ``` -All tests, as executed in CI, can be run with (very slow): - -```bash -uvx tox -``` - The repository includes several tox environments for different testing scenarios: - `static` - Linting, type checking and spell checking. @@ -85,7 +98,13 @@ It is recommended to run the `static` checks locally before pushing changes to a uvx tox -e static # Run linting and type checking. ``` -All environments in parallel (very slow, even in parallel): +All environments can be executed using (very slow, not recommended, even in parallel): + +```bash +uvx tox +``` + +Environments can be executed in parallel with (still very slow): ```bash uvx tox run-parallel From 7396ac7640a8891aeb78558e52e0cc66b8267d9a Mon Sep 17 00:00:00 2001 From: danceratopz Date: Thu, 4 Sep 2025 17:09:38 +0200 Subject: [PATCH 9/9] docs: clarify that geth is only required for syncing and verifying mainnet blocks --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fab1687d32..89ec5885d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ Running the tests necessary to merge into the repository requires: - [`uv`](https://docs.astral.sh/uv/) package manager, - Python 3.11.x, - [PyPy](https://www.pypy.org/) [7.3.19](https://downloads.python.org/pypy/) or later (typically only required by execution-specs maintainers), -- `geth` installed and present in `$PATH` +- `geth` installed and present in `$PATH` (only required by users who would like to sync and verify mainnet blocks using EELS; not required for typical specification or test development). #### Installing `uv`