docs(deps): document how to manage eest dependencies (#1388)

Co-authored-by: spencer <[email protected]>

Author: danceratopz

docs/CHANGELOG.md

@@ -55,6 +55,7 @@ consume cache --help
 - 🔀 Bump the version of `execution-specs` used by the framework to the package [`ethereum-execution==1.17.0rc6.dev1`](https://pypi.org/project/ethereum-execution/1.17.0rc6.dev1/); bump the version used for test fixture generation for forks < Prague to current `execution-specs` master, [fa847a0](https://github.com/ethereum/execution-specs/commit/fa847a0e48309debee8edc510ceddb2fd5db2f2e) ([#1310](https://github.com/ethereum/execution-spec-tests/pull/1310)).
 - 🐞 Init `TransitionTool` in `GethTransitionTool` ([#1276](https://github.com/ethereum/execution-spec-tests/pull/1276)).
 - 🔀 Refactored RLP encoding of test objects to allow automatic generation of tests ([#1359](https://github.com/ethereum/execution-spec-tests/pull/1359)).
+- ✨ Document how to manage `execution-spec-tests` package dependencies ([#1388](https://github.com/ethereum/execution-spec-tests/pull/1388)).
 
 #### Packaging
 

docs/dev/deps_and_packaging.md

@@ -0,0 +1,67 @@
+# EEST Dependency Management and Packaging
+
+EEST uses [`uv`](https://docs.astral.sh/uv/) to manage and pin its dependencies.
+
+## Managing Dependencies
+
+We aim to provide specific [version specifiers](https://peps.python.org/pep-0440/#version-specifiers) for each of our direct and extra dependencies.
+!!! note "Packages should be managed via `uv`"
+
+    Dependencies should be managed using `uv` on the command-line to ensure that version compatibility is ensured across all dependencies and that `uv.lock` is updated as required.
+
+### Adding/modifying direct dependencies
+
+These are packages listed in the project's direct dependencies, i.e., in `pyproject.toml` `[project]` section:
+
+```toml
+[project]
+...
+dependencies = [
+    "click>=8.1.0,<9",
+    ...
+    "pytest-regex>=0.2.0,<0.3",
+]
+```
+
+or, for source package dependencies (directly installed via a `git+` specifier from Github), in the `[tool.uv.sources]` section:
+
+```toml
+[tool.uv.sources]
+ethereum-spec-evm-resolver = { git = "https://github.com/petertdavies/ethereum-spec-evm-resolver", rev = \
+...
+```
+
+!!! example "Example: Updating direct dependencies"
+
+    Example of a package dependency update:
+    ```console
+    uv add "requests>=2.31,<2.33"
+    ```
+
+    Example of a source dependency update:
+    ```console
+    uv add "ethereum-spec-evm-resolver @ git+https://github.com/petertdavies/ethereum-spec-evm-resolver@623ac4565025e72b65f45b926da2a3552041b469"
+    ```
+
+### Adding/modifying optional dependencies
+
+These are packages in the optional "extra" groups: `lint`, `docs`, `test`, defined in the `pyproject.toml`:
+
+```toml
+[project.optional-dependencies]
+test = ["pytest-cov>=4.1.0,<5"]
+lint = [
+    "ruff==0.9.4",
+    "mypy>=1.15.0,<1.16",
+    "types-requests>=2.31,<2.33",
+]
+docs = [
+    ...
+]
+```
+
+!!! example "Example: Updating an optional dependency"
+
+    ```
+    uv add --optional lint "types-requests>=2.31,<2.33"
+    ```

docs/dev/index.md

@@ -1,13 +1,17 @@
 # Developer Documentation
 
-This documentation is aimed at maintainers of `execution-spec-tests` but may be helpful during test case development:
+This documentation is aimed at `execution-spec-tests` developers:
 
 - [Managing configurations](./configurations.md): Instructions for setting up and modifying test configurations.
 - [Interactive usage](./interactive_usage.md): Guide on interactive use of EEST packages using `ipython`.
-- [Generating documentation](./docs.md): Steps to create and build documentation for the project.
 - [Documenting CLI commands](./documenting_clis.md): Instructions for documenting command line interfaces (CLIs).
 - [Coding style](./coding_style.md): Standards and best practices for code formatting and to maintain consistency across the repository.
 - [Logging](./logging.md): Documentation on using the custom logging system with enhanced features.
 - [Enabling pre-commit checks](./precommit.md): A guide for setting up pre-commit hooks to enforce code quality before commits.
 - [Running github actions locally](./test_actions_locally.md): Instructions for testing GitHub Actions workflows on your local machine to streamline development and debugging.
 - [Porting tests](./porting_legacy_tests.md): A guide to porting legacy ethereum tests to EEST.
+
+These sections are primarily aimed at `execution-spec-tests` maintainers:
+
+- [Generating documentation](./docs.md): Steps to create and build documentation and manage documentation versions.
+- [Managing dependencies and packaging](./deps_and_packaging.md): How to update EEST dependencies.

whitelist.txt

@@ -874,3 +874,4 @@ EESTLogger
 Formatters
 UI
 asctime
+petertdavies