From 0f618bcfe59efa028566ead124e13ef3e4cda317 Mon Sep 17 00:00:00 2001 From: VolodymyrBg Date: Wed, 16 Apr 2025 17:30:08 +0300 Subject: [PATCH 1/3] feat(docs): create release documentation for EEST super users --- docs/releases.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/releases.md diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 00000000000..6233901289a --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,118 @@ +# Releases + +This page provides information about Ethereum Execution Spec Tests (EEST) releases for advanced users who need to work with multiple test fixture sets or understand how EEST releases are structured and managed. + +## Types of Releases + +EEST provides two main types of releases: + +### Full Releases + +Full releases are published with version tags following semantic versioning (e.g., `v3.0.0`). These releases contain comprehensive test fixtures for deployed forks and are considered stable for production use. + +Full releases typically: +- Are tagged with version numbers like `v3.0.0`, `v3.1.0`, etc. +- Are not marked as "pre-releases" in GitHub +- Contain test fixtures for all stable Ethereum forks +- Undergo thorough testing and review +- Have detailed release notes with a descriptive name (e.g., "Petřín (v3.0.0)") + +Full releases are recommended for general use, client compatibility testing, and Continuous Integration (CI) pipelines. + +### Pre-releases + +Pre-releases are published with feature-specific tags in the format `feature-name@vX.Y.Z` (e.g., `pectra-devnet-5@v1.0.0`, `eip7692@v2.1.0`). These releases contain test fixtures for features under development, devnets, or specific EIPs that haven't been deployed to mainnet yet. + +Pre-releases typically: +- Are tagged with feature-specific tags like `feature-name@vX.Y.Z` +- Are marked as "pre-releases" in GitHub +- Focus on specific features, EIPs, or devnets +- May not be as thoroughly tested as full releases +- May contain breaking changes or experimental features +- Have detailed release notes explaining the included EIPs and changes + +Pre-releases are invaluable for client teams implementing new features, testing devnets, or working on specific EIPs in parallel. + +## Release Naming Conventions + +EEST follows these naming conventions for releases: + +- **Full releases**: `vX.Y.Z` (e.g., `v3.0.0`) + - `X`: Major version (breaking changes) + - `Y`: Minor version (new features, non-breaking) + - `Z`: Patch version (bug fixes) + +- **Pre-releases**: `feature-name@vX.Y.Z` (e.g., `pectra-devnet-5@v1.0.0`) + - `feature-name`: The name of the feature, devnet, or EIP + - `vX.Y.Z`: Version number specific to this feature + +## Release Process + +EEST releases are created automatically through GitHub Actions workflows: + +1. For **full releases** (`v3.0.0`), the workflow is triggered when a tag matching the pattern `v[0-9]+.[0-9]+.[0-9]+*` is pushed. + +2. For **pre-releases** (`feature-name@vX.Y.Z`), the workflow is triggered when a tag matching the pattern `*@v*` is pushed. + +The release process: +1. Builds test fixtures for the specified release +2. Creates a draft release in GitHub +3. Attaches the test fixtures as assets to the release +4. Generates release notes (which can then be edited before publishing) + +## Using Releases in EEST + +EEST provides several ways to consume release fixtures: + +### Command Line + +You can use the `consume` command to fetch and use fixtures from a release: + +```bash +# Use the latest full release +consume direct --input stable@latest + +# Use a specific release version +consume direct --input v3.0.0 + +# Use a pre-release for a specific feature +consume direct --input pectra-devnet-5@v1.0.0 +``` + +### In Your Code + +You can use the `FixturesSource` class to programmatically fetch and use fixtures from a release: + +```python +from pytest_plugins.consume.consume import FixturesSource + +# Use the latest full release +fixtures = FixturesSource.from_release_spec("stable@latest") + +# Use a specific release version +fixtures = FixturesSource.from_release_spec("v3.0.0") + +# Use a pre-release for a specific feature +fixtures = FixturesSource.from_release_spec("pectra-devnet-5@v1.0.0") +``` + +## Release Notes + +Release notes are an important part of each release. They typically include: + +- The list of included EIPs and their specific versions +- Breaking changes and their impact +- New test formats or changes to existing formats +- Important notes for users of the release + +You can find release notes on the [GitHub Releases page](https://github.com/ethereum/execution-spec-tests/releases). + +## Documentation Versions + +Documentation for each release is also published, allowing you to view the documentation specific to a particular release. You can find the documentation selector in the top-right corner of this page. + +Documentation for pre-releases is available at URLs of the form: +`https://eest.ethereum.org/feature-name@vX.Y.Z/` + +For example, documentation for the `pectra-devnet-5@v1.0.0` release would be available at: +`https://eest.ethereum.org/pectra-devnet-5@v1.0.0/` From f9cc9944eb8307ba8f00fbf63f6e6e44c178f81b Mon Sep 17 00:00:00 2001 From: VolodymyrBg Date: Wed, 16 Apr 2025 17:30:39 +0300 Subject: [PATCH 2/3] add realeses.md --- docs/navigation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/navigation.md b/docs/navigation.md index ecf1217c0b1..0b5a2df055d 100644 --- a/docs/navigation.md +++ b/docs/navigation.md @@ -6,6 +6,7 @@ * [VS Code Setup](getting_started/setup_vs_code.md) * [Repository Overview](getting_started/repository_overview.md) * [Getting Help](getting_started/getting_help.md) + * [Releases](releases.md) * [Writing Tests](writing_tests/index.md) * [Adding a New Test](writing_tests/adding_a_new_test.md) * [Types of Test](writing_tests/types_of_tests.md) From 3571aaac86bd4175fd96cd9b6550f8b694560c79 Mon Sep 17 00:00:00 2001 From: VolodymyrBg Date: Wed, 16 Apr 2025 17:55:41 +0300 Subject: [PATCH 3/3] Update releases.md --- docs/releases.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/releases.md b/docs/releases.md index 6233901289a..7bd544ca430 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -15,23 +15,23 @@ Full releases typically: - Are not marked as "pre-releases" in GitHub - Contain test fixtures for all stable Ethereum forks - Undergo thorough testing and review -- Have detailed release notes with a descriptive name (e.g., "Petřín (v3.0.0)") +- Have detailed release notes with a descriptive name (e.g., "v3.0.0" with codename) Full releases are recommended for general use, client compatibility testing, and Continuous Integration (CI) pipelines. ### Pre-releases -Pre-releases are published with feature-specific tags in the format `feature-name@vX.Y.Z` (e.g., `pectra-devnet-5@v1.0.0`, `eip7692@v2.1.0`). These releases contain test fixtures for features under development, devnets, or specific EIPs that haven't been deployed to mainnet yet. +Pre-releases are published with feature-specific tags in the format `feature-name@vX.Y.Z` (e.g., `network-testnet-5@v1.0.0`, `eip7692@v2.1.0`). These releases contain test fixtures for features under development, development networks, or specific EIPs that haven't been deployed to mainnet yet. Pre-releases typically: - Are tagged with feature-specific tags like `feature-name@vX.Y.Z` - Are marked as "pre-releases" in GitHub -- Focus on specific features, EIPs, or devnets +- Focus on specific features, EIPs, or development networks - May not be as thoroughly tested as full releases - May contain breaking changes or experimental features - Have detailed release notes explaining the included EIPs and changes -Pre-releases are invaluable for client teams implementing new features, testing devnets, or working on specific EIPs in parallel. +Pre-releases are invaluable for client teams implementing new features, testing development networks, or working on specific EIPs in parallel. ## Release Naming Conventions @@ -42,8 +42,8 @@ EEST follows these naming conventions for releases: - `Y`: Minor version (new features, non-breaking) - `Z`: Patch version (bug fixes) -- **Pre-releases**: `feature-name@vX.Y.Z` (e.g., `pectra-devnet-5@v1.0.0`) - - `feature-name`: The name of the feature, devnet, or EIP +- **Pre-releases**: `feature-name@vX.Y.Z` (e.g., `network-testnet-5@v1.0.0`) + - `feature-name`: The name of the feature, development network, or EIP - `vX.Y.Z`: Version number specific to this feature ## Release Process @@ -76,12 +76,12 @@ consume direct --input stable@latest consume direct --input v3.0.0 # Use a pre-release for a specific feature -consume direct --input pectra-devnet-5@v1.0.0 +consume direct --input network-testnet-5@v1.0.0 ``` ### In Your Code -You can use the `FixturesSource` class to programmatically fetch and use fixtures from a release: +You can use the fixtures source class to programmatically fetch and use fixtures from a release: ```python from pytest_plugins.consume.consume import FixturesSource @@ -93,7 +93,7 @@ fixtures = FixturesSource.from_release_spec("stable@latest") fixtures = FixturesSource.from_release_spec("v3.0.0") # Use a pre-release for a specific feature -fixtures = FixturesSource.from_release_spec("pectra-devnet-5@v1.0.0") +fixtures = FixturesSource.from_release_spec("network-testnet-5@v1.0.0") ``` ## Release Notes @@ -114,5 +114,5 @@ Documentation for each release is also published, allowing you to view the docum Documentation for pre-releases is available at URLs of the form: `https://eest.ethereum.org/feature-name@vX.Y.Z/` -For example, documentation for the `pectra-devnet-5@v1.0.0` release would be available at: -`https://eest.ethereum.org/pectra-devnet-5@v1.0.0/` +For example, documentation for the `network-testnet-5@v1.0.0` release would be available at: +`https://eest.ethereum.org/network-testnet-5@v1.0.0/`