You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The execution-specs repo manages the implementation of multiple Ethereum forks in parallel via separate git branches, for example:
forks/osaka (default branch),
forks/amsterdam,
eips/amsterdam/eip-7928.
Goal
In order to support the developer community working on Scheduled For Inclusion (SFI'd) versions (or other substantial efforts), the execution-specs HTML pages should provide versioned sites matching each of these larger development efforts. I.e., the HTML pages should contain a version that corresponds to one of these branches. The docs of each branch are not to be versioned; they will reflect the HEAD of each branch.
Status Quo Prior to The Weld
Repository
Branch Strategy
Docs Content
Versioned
URL (with version example)
execution-specs
Maintains fork-specific code in corresponding branches (e.g., forks/amsterdam)
An important part of this documentation (originally in EEST) is the "Test Case Reference", e.g., for the v5.0.0 release, which becomes branch-dependent post-Weld. These are HTML pages, included in the mkdocs generated site, generated from the tests/ test module docstrings and metadata that contain:
An overview of all test cases, organized by fork and EIP or target area, e.g., benchmarks; the structure reflects the structure of the tests/ directory. The individual test pages (attempt to) visualize the parameter combinations that each test uses. This information is extracted from the docstrings and the test parameters via a custom plugin.
For newer, EIP-specific test folders: An EIP Checklist, which displays the current progress made in testing this EIP and which tests have been implemented and which are outstanding.
While the developer docs will mainly be fork-agnostic (although new features may need to be documented in the guides on "Writing Tests", for example), the Test Case Reference is now, as part of execution-specs, heavily branch dependent.
Suggestion for Versioning
The HEAD of every branch that has a ongoing substantial implementation effort will be included as a version that can be selected on the documentation page. In this manner, the available tests for each fork, respectively EIP, can be browsed corresponding to its branch.
Implementation Idea (only for top-level version selector)
Each actively developed branch (e.g. a fork or major EIP) builds its own MkDocs + spec output and uploads it as a zipped artifact.
A single aggregator workflow on the default branch then downloads the latest artifacts from all allow-listed branches, unpacks them into subpaths matching their branch names (e.g. /forks/osaka/, /eips/amsterdam/eip-7928/), mirrors the default branch to the site root (/ and /spec/), generates a versions.json manifest for the UI dropdown, and publishes the combined result as one GitHub Pages site.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Background and Top-Level Goal
The
execution-specsrepo manages the implementation of multiple Ethereum forks in parallel via separate git branches, for example:forks/osaka(default branch),forks/amsterdam,eips/amsterdam/eip-7928.Goal
In order to support the developer community working on Scheduled For Inclusion (SFI'd) versions (or other substantial efforts), the
execution-specsHTML pages should provide versioned sites matching each of these larger development efforts. I.e., the HTML pages should contain a version that corresponds to one of these branches. The docs of each branch are not to be versioned; they will reflect the HEAD of each branch.Status Quo Prior to The Weld
An important part of this documentation (originally in EEST) is the "Test Case Reference", e.g., for the v5.0.0 release, which becomes branch-dependent post-Weld. These are HTML pages, included in the mkdocs generated site, generated from the
tests/test module docstrings and metadata that contain:tests/directory. The individual test pages (attempt to) visualize the parameter combinations that each test uses. This information is extracted from the docstrings and the test parameters via a custom plugin.While the developer docs will mainly be fork-agnostic (although new features may need to be documented in the guides on "Writing Tests", for example), the Test Case Reference is now, as part of execution-specs, heavily branch dependent.
Suggestion for Versioning
The HEAD of every branch that has a ongoing substantial implementation effort will be included as a version that can be selected on the documentation page. In this manner, the available tests for each fork, respectively EIP, can be browsed corresponding to its branch.
The base URL can initially be the Github pages: https://ethereum.github.io/execution-specs/, but preferably be
steel.ethereum.foundation/docs/.Implementation Idea (only for top-level version selector)
Each actively developed branch (e.g. a fork or major EIP) builds its own MkDocs + spec output and uploads it as a zipped artifact.
A single aggregator workflow on the default branch then downloads the latest artifacts from all allow-listed branches, unpacks them into subpaths matching their branch names (e.g. /forks/osaka/, /eips/amsterdam/eip-7928/), mirrors the default branch to the site root (/ and /spec/), generates a
versions.jsonmanifest for the UI dropdown, and publishes the combined result as one GitHub Pages site.All reactions