ethereum/EIPs: the repository where Ethereum's standards are written down

What ethereum/EIPs actually is, and who writes in it

This is a document repository. It tracks past and ongoing changes to Ethereum as numbered proposals, and the README describes the goal as standardizing and providing high-quality documentation for Ethereum itself and the conventions built on top of it. The process that governs publication is EIP-1, which lives in the same repository at EIPS/eip-1.md and is the document you read before anything else.

The audience is narrow. You are in the right place if you are drafting a standard, reviewing one, or citing one in a specification of your own. You are in the wrong place if you want help implementing a standard. The README says plainly that the repository is for documenting standards and not for help implementing them, and points such inquiries at the Ethereum Stack Exchange. Questions about a specific proposal go to the discussion thread named by that proposal's discussions-to tag.

There is also an editorial role. EIP-5069, stored at EIPS/eip-5069.md, describes how to become an EIP Editor, so the repository carries its own governance for who merges what.

The six categories that decide where a proposal belongs

The status page at eips.ethereum.org sorts proposals into six buckets, and the category is not cosmetic: it determines what kind of consensus, if any, a proposal needs. Core EIPs change the consensus protocol. Networking EIPs specify the peer-to-peer layer. Interface EIPs standardize how users and applications interact with the chain. ERCs specify application layer standards, meaning how applications running on Ethereum talk to each other. Meta EIPs are miscellaneous improvements that still require some form of consensus. Informational EIPs are non-standard and require no consensus at all.

That last pair is the one people get wrong. An informational proposal is a description, not a rule, and nothing obliges anyone to follow it. If your document needs the ecosystem to agree on behavior, it is not informational, however it is written.

The ERC split is the other thing to internalize. The README states that the repository recently underwent a separation of ERCs and EIPs, that ERCs are now accessible at https://github.com/ethereum/ercs, and that all new ERCs and updates to existing ones must be directed there. The editors note the inconvenience in the README itself. So a token standard drafted today belongs in the other repository, even though the ERC listing still appears on the status page.

Install eipw and validate a proposal before you push

Every pull request has to pass automated checks before it can be merged automatically. EIP-1 rules are enforced by eipw, HTML formatting and broken links by HTMLProofer, spelling by CodeSpell, and Markdown style by markdownlint. The review bot decides when a PR can be auto-merged. You can run the EIP validator on your own machine, which is the fastest way to avoid a round trip.

The README instructs you to make sure Cargo's bin directory is on your PATH, typically $HOME/.cargo/bin, then install and run eipw with the repository config:

cargo install eipw
eipw --config ./config/eipw.toml <INPUT FILE / DIRECTORY>

Replace the placeholder with a path to your draft file or a directory of them. The config lives at config/eipw.toml in the repository, so run the command from the repository root, or point --config at that file's real location.

Spelling deserves a warning. The README notes that CodeSpell produces false positives, and that when this happens you should submit a pull request editing config/.codespell-whitelist, and only that file. Adding a word anywhere else will not silence the check.

Build the status page locally with Ruby 3.1.4

The site at eips.ethereum.org is a Jekyll build, and the README walks through running it locally. First confirm your Ruby version, because the README states that Ruby 3.1.4 is required and that later versions are not supported, linking to a known failure mode. Then install Bundler and the dependencies:

gem install bundler
bundle install

With dependencies in place, serve the site:

bundle exec jekyll serve

The README says to preview the local Jekyll site in your browser at http://localhost:4000. The repository layout matches that: _config.yml, _layouts/, _includes/, _data/ and a set of category pages (core.html, networking.html, interface.html, erc.html, meta.html, informational.html, all.html) sit at the top level alongside EIPS/, assets/, config/ and rss/.

The Ruby pin is the practical friction here. If your machine already runs a newer Ruby, the README's own link says the build can fail with an undefined method error, and the fix is not a patch to the Gemfile but switching interpreters. A container or a version manager is the sane way to keep 3.1.4 isolated from everything else you build.

Where this repository is the wrong tool

The most common mistake is treating ethereum/EIPs as a help desk. The README says implementation questions belong on the Ethereum Stack Exchange, and proposal-specific concerns belong in the discussion thread named by the discussions-to tag. Filing either as a pull request or an issue against this repository will not get you an answer.

The second mistake is drafting before discussing. The README states that before you write an EIP, ideas must be thoroughly discussed on Ethereum Magicians or Ethereum Research, and that consensus must be reached first. A polished draft with no prior discussion has no path forward in this process, no matter how good the text is.

The third is citation. The README defines the canonical URL for a proposal that has reached draft status as https://eips.ethereum.org/, and says to consider any document not published there as a working paper. It goes further: proposals with a status of draft, review or last call are incomplete drafts whose specification is likely to change. If you are building against a proposal in one of those states, pin the version you read and expect the text to move. Nothing in the README describes a stability guarantee for those statuses, because there is not one.

How this differs from a conventional standards body

Compare it to the IETF or the W3C. Those organizations publish numbered documents too, but the artifact is the output of a working group with formal membership, meeting minutes and a chair. Here the artifact is a Markdown file in a Git repository, and the review surface is a pull request. The README's description of the pipeline is entirely tooling: eip-review-bot for merge decisions, eipw for EIP-1 conformance, HTMLProofer for links, CodeSpell for spelling, markdownlint for style. Consensus is not produced by that tooling. It is produced on Ethereum Magicians or Ethereum Research beforehand, and the repository records the result.

That split is the design. Git gives you line-level diffs, blame and a permanent public history of how a specification's wording changed. It gives you nothing for building agreement. A working group can compel its members to show up; a repository cannot. The README's insistence on prior discussion is an admission of that gap.

The ERC move to ethereum/ercs is the other structural difference worth noting. Rather than let one repository absorb every application layer standard, the editors split the fast-moving application surface away from the protocol documents. The README apologizes for the inconvenience, which is fair: anyone with bookmarks or scripts pointed at the old ERC paths has work to do.

Editorial conclusion

Adopt this repository as a reading and writing surface if you need to cite, draft or review an Ethereum standard, and expect to run eipw and the Jekyll build locally before opening a pull request. Do not treat it as a support channel for implementing a standard, and do not send new ERCs here: the README states that all new ERCs and updates to existing ones must go to https://github.com/ethereum/ercs. Verify first which of the six categories your proposal falls into, and confirm the Ruby version constraint, since the README says Ruby 3.1.4 is required and later versions are not supported.

Frequently asked questions

Official sources

1. ethereum/EIPs on GitHub
2. Issues
3. License: CC0-1.0
4. Project website
5. README