feat(doc): re-write readme/top-level docs and add specs section to html docs#2677
Open
danceratopz wants to merge 18 commits intoethereum:forks/amsterdamfrom
Open
feat(doc): re-write readme/top-level docs and add specs section to html docs#2677danceratopz wants to merge 18 commits intoethereum:forks/amsterdamfrom
danceratopz wants to merge 18 commits intoethereum:forks/amsterdamfrom
Conversation
Introduce a top-level `Specs` section in the mkdocs navigation and a new `docs/specs/index.md` page that explains what EELS is, the coordination problem it solves, why Python was chosen, the Correct/Complete/Accessible principles, and the fork-as-a-copy (WET) model. This is the anchor page for further specs-side documentation (writing specs, adding a new EIP, spec releases, protocol history); those pages land in follow-up commits.
The full mainnet hardfork table, the "clarifications without a protocol release" table, and the Paris/Shanghai activation note now live on a dedicated `docs/specs/protocol_history.md` page linked from the Specs overview and the mkdocs navigation. `README.md` keeps a one-line pointer to the new page. Fork-manifest links switch from repo-relative paths (`/src/ethereum/...`) to absolute GitHub URLs on `forks/amsterdam` so they resolve correctly from the rendered docs site.
…p.md Pure rename so `git log --follow` (and `mkdocs-git-authors-plugin` by extension) continues to trace the file's history back to the original author, Guruprasad Kamath. Content modernization for the post-Weld world lands in the follow-up commit.
Post-Weld rewrite of the EIP author's manual. The cross-repo references to `execution-spec-tests` are replaced with pointers to in-tree tests under `./tests/`; the step-by-step workflow points at the in-tree `ethereum_spec_tools` utilities. The YouTube opcode tutorial link is preserved. The rename from `EIP_AUTHORS_MANUAL.md` to `docs/specs/adding_a_new_eip.md` was done as a pure `git mv` in the previous commit so `git log --follow` (and therefore the `mkdocs-git-authors-plugin`) continues to attribute the earlier content to its original author. Co-authored-by: Guruprasad Kamath <guru241987@gmail.com>
Extracts the style, comments, docstrings, constants, and cross-fork sections from `CONTRIBUTING.md` into a dedicated `docs/specs/writing_specs.md` page, alongside documentation for the `ethereum_spec_tools` CLI utilities (New Fork Tool, Sync Tool, Patch Tool, Lint Tool) and the `--evm-trace` debugging flag. The EIP-attributed-comment pitfall is preserved as a collapsible detail block so it remains readable without dominating the page. `CONTRIBUTING.md` is untouched in this commit; the slimming down to who/how/what happens in a follow-up. The `adding_a_new_eip` page gets its `Writing Specs` link back in this commit now that the target exists.
`CONTRIBUTING.md` now focuses on who the project welcomes contributions from, how to raise issues/PRs, and the three guiding principles (Correct, Complete, Accessible). The remaining sections point at the authoritative docs: - Environment setup, `uv`/`just`/shell completions, Python version, and the full recipe list go to `docs/getting_started/installation.md`. - Naming/comments/docstrings/constants/cross-fork discipline, and the `ethereum_spec_tools` CLI utilities go to `docs/specs/writing_specs.md`. - The `--evm-trace` debugging tip lives in `docs/specs/writing_specs.md`. - The `MYPY_CACHE_DIR` worktree tip is already covered in the installation docs. `copy_repo_docs_to_mkdocs.py` learns two new link rewrites so the repo-relative `docs/...` paths in `CONTRIBUTING.md` work both when viewed on GitHub and when the file is copied to `docs/getting_started/contributing.md` for the rendered site.
The old `RELEASING.md` mixed two audiences: contributors (who want to understand the version-number scheme when reading `pyproject.toml` or proposing a release) and maintainers (who cut the tag, publish to PyPI, and file the GitHub release). Split along that seam: - `docs/specs/spec_releases.md` covers the versioning scheme (format, examples, and the current-to-next lookup table), sitting alongside the other specs-side documentation. - `docs/dev/releasing.md` is the maintainer runbook (updating the version in source, tagging, GitHub release, PyPI publish). Each page links to the other so a reader landing on either one can find the half they need.
Post-Weld `README.md` becomes the GitHub-landing hook: a short description, pointers to the rendered documentation site, the `docc`-rendered pyspec, the protocol history page, a single-tab Quick Start cribbed from `docs/getting_started/installation.md`, and the license. The README now treats `docs/getting_started/installation.md` as the source of truth for environment setup: the Python-version line reflects the 3.11 to 3.14 range (recommending 3.12) rather than the stale "Python 3.11+"; the "Building Specification Documentation" and "Browsing Updated Documentation" sections collapse into a single `mkdocs serve` / `just docs-spec` note; and the "work-in-progress" placeholder heading is gone.
Use the full word "Specifications" in the navigation sidebar and the section index H1. The folder name under `docs/specs/` and the URL path are unchanged.
The opening section now leads with "Client Diversity requires
Coordination" and frames client diversity as a positive property
(resilience, no privileged implementation, permissionless participation)
rather than opening on the coordination *problem*. Coordination follows
as the natural consequence of that diversity: a multi-client network
needs a precise shared description of behaviour, and EELS is it.
Links the ethereum.org client-diversity page for readers who want the
full argument. The Python-versus-prose point is kept but slimmed of
incidental color ("implementation differences in early EIPs are part of
the lore") that didn't add to the reframed narrative.
Consecutive prose lines and list-item continuations are collapsed onto a single line per paragraph / list item. Fenced code blocks, tables, HTML blocks, headings, admonition markers, blockquotes, and link reference definitions are preserved verbatim. Matches the single-line-per-paragraph style already applied to the opening paragraph of `docs/specs/index.md`, and makes the files easier to diff on prose edits.
Matches the single-line-per-paragraph style now used across `docs/specs/*.md`, for cleaner future prose diffs. The blockquote content under the `[!IMPORTANT]` alert is also collapsed to a single line after the marker.
`CONTRIBUTING.md` no longer embeds its own abbreviated install commands; it points at the [Quick Start](README.md#quick-start) for the short version and at the Installation guide for full setup. Avoids a third copy of the install commands drifting out of sync. `copy_repo_docs_to_mkdocs.py` rewrites `README.md#quick-start` to `installation.md#quick-start` when copying `CONTRIBUTING.md` into the mkdocs site, since the rendered site has no `README.md`.
Paragraphs are collapsed to a single line each, matching the style now used across `docs/specs/*.md` and `CONTRIBUTING.md` for cleaner future prose diffs. `mkdocs serve` is replaced with `just docs-serve-fast` so the README drives users through the repo's task runner rather than a raw `uv run` invocation; the `just docs-spec` call gets its own code block for symmetry. Both fences use the `console` language now that they are pure shell commands.
danceratopz
changed the title
danceratopz
added
A-doc
danceratopz
changed the title
Member
Author
|
The README wasn't very good in the first sweep, so I fixed it up. CONTRIBUTING also got a few improvements. I force pushed to do a From my side, this would be good (enough) to go! The new HTML Specifications section isn't perfect by any stretch, but happy to improve in follow-up PRs. |
danceratopz
changed the title
Member
Author
|
Here's a link to the rendered README: |
felix314159
approved these changes
Apr 20, 2026
Contributor
felix314159
left a comment
felix314159
left a comment
There was a problem hiding this comment.
ty for taking care of our docs, many client team questions can be answered directly by linking to some part of them
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🗒️ Description
./docs/specs/)../docs/.Specificatoinssection in the mkdocs site.../docs/).New pages
docs/specs/index.md: overview of EELS, framed around client diversity requiring coordination, the Correct/Complete/Accessible principles, and the WET/fork-as-a-copy model.docs/specs/writing_specs.md: style rules (naming, comments, docstrings, constants), cross-fork discipline, theethereum_spec_toolsCLI utilities (New Fork Tool, Sync Tool, Patch Tool, Lint Tool), and the--evm-tracedebugging flag.docs/specs/adding_a_new_eip.md: the EIP lifecycle and the concrete workflow for landing a new EIP insrc/ethereum/forks/<FORK_NAME>/.docs/specs/spec_releases.md: contributor-facing explanation of the EELS versioning scheme (format, examples, current-to-next lookup table).docs/specs/protocol_history.md: the full mainnet hardfork table, the "clarifications without a protocol release" table, and the Paris/Shanghai activation note.docs/dev/releasing.md: maintainer runbook (version bump, tagging, GitHub release, PyPI publish), split out from the contributor-facing versioning docs.Todo
EIP_AUTHORS_MANUAL.md.🔗 Related Issues or PRs
Complements #2662 (EEST-side docs reorg). Both PRs can land independently.
✅ Checklist
All: Ran fast static checks to avoid unnecessary CI fails, see also Code Standards and Enabling Pre-commit Checks:
just staticAll: PR title adheres to the repo standard - it will be used as the squash commit message and should start
type(scope):.All: Considered updating the online docs in the ./docs/ directory.
All: Set appropriate labels for the changes (only maintainers can apply labels).
Tests: Ran
mkdocs servelocally and verified the auto-generated docs for new tests in the Test Case Reference are correctly formatted.Cute Animal Picture