# The EIP Overhaul

**TLDR: First I give an overview of the EIP process and its changes in 2019. Then I propose a new process, mostly influenced by the RFC and W3C processes.**

Preface: I have been involved with [EIPs](https://github.com/ethereum/EIPs) (Ethereum Improvement Proposals) since early 2016, initially as a contributor, but later entangled in the "AllCoreDev process" and editorial tasks.

[toc]

## Current Process

The current EIP repository mixes two very different processes:
1. Specification
2. Network rollout (hard forks)

Both of these are partially defined by mostly [EIP-1](https://eips.ethereum.org/EIPS/eip-1) and [EIP-233](https://eips.ethereum.org/EIPS/eip-233). Later this was extended with [EIP-2378](https://eips.ethereum.org/EIPS/eip-2378).

During 2019 several changes were proposed, four relevant ones for the statuses:
1. [Introduce Review status](https://github.com/ethereum/EIPs/pull/1725)
2. [Rename Accepted to Ready](https://github.com/ethereum/EIPs/pull/2279)
3. [Introduce Abandoned status](https://github.com/ethereum/EIPs/pull/2051)
4. [Remove Deferred status](https://github.com/ethereum/EIPs/pull/2162)

The first two had similar motivations, but are slightly different. The Review status would introduce a stage where changes are not rapid, yet the proposal is clear enough for wider review. The Ready status is just a small incremental change to soften the tone of Accepted, but still keeps the hard fork process in EIP-1.

The Abandoned status was introduced in an attempt to clean up a lot abandoned drafts. Apparently an unused Withdrawn status existed in the past but [was removed](https://github.com/ethereum/EIPs/pull/1100).

The Deferred status was removed because it fell out of use, due to changes in EIP-233 and EIP-2378.

There were various mentions of removing other hard fork related statuses, such as Accepted and Rejected too.

*Note that in the graphs below I will not give a complete explanation of what each status means. Please read EIP-1 to understand each edge case. However, reading the "Proposed Process" should reasonably explain it.*

The complexity was discussed in more depth [last June (2019)](https://gitter.im/ethereum/EIPs?at=5d153824ddc34e0f13f9ed65). If every single status is considered, this is the progress graph (<small>this was prior to the removal of Deferred</small>):

<!---->

digraph EIP1 {
concentrate=true

Idea -> Draft; 
Draft -> Active;
Draft -> "Last Call";
Draft -> Abandoned;
Abandoned -> Draft;
"Last Call" -> Final;
"Last Call" -> Accepted;
Accepted -> Final;
Accepted -> Deferred;
Accepted -> Rejected;
Final -> Superseded;
Deferred -> Final;
}

*I took the liberty at the time to assume that Last Call could move to Abandoned, albeit it was not documented.*

What I have not mentioned yet there are two "kinds" of EIPs which have different flows and not all the combinations above are valid.

The "Core" EIPs have the following flow:

digraph EIP1 {
concentrate=true

Idea -> Draft; 
Draft -> Active;
Draft -> "Last Call";
Draft -> Abandoned;
Abandoned -> Draft;
"Last Call" -> Draft;
"Last Call" -> Accepted;
Accepted -> Draft;
Accepted -> Rejected;
Accepted -> Deferred;
Accepted -> Final;
Final -> Superseded;
Deferred -> Final;
}

Albeit it must be noted the Last Call status was not utilised for "Core" EIPs up until lately.

While "non-Core" EIPs have the following:

digraph EIP1 {
concentrate=true

Idea -> Draft; 
Draft -> Active;
Draft -> "Last Call";
Draft -> Abandoned;
Abandoned -> Draft;
"Last Call" -> Draft;
"Last Call" -> Final;
Final -> Superseded;
}

In May 2020 I have [proposed](https://github.com/ethereum-cat-herders/EIPIP/issues/15) a much simpler combined alternative:
<!---->

digraph EIP1 {
concentrate=true

Idea -> Draft; 
Draft -> Review;
Draft -> "Withdrawn/Abandoned";
Review -> "Last Call";
Review -> Active;
Review -> "Withdrawn/Abandoned";
"Last Call" -> Final;
Final -> Superseded;
}

The goal here was to incorporate the Review state and remove any attempt at coordinating hard forks. This allows for an identical flow for "Core" and "non-Core" EIPs. However I have conveniently ignored where, how, and who will coordinate the hard fork part.

This [was discussed](https://github.com/ethereum-cat-herders/EIPIP/blob/master/All%20EIPIP%20Meetings/Meeting%20008.md#5-separation-of-eip-process-and-hard-fork-coordination), but as it is usually with the EIP process, changes got stuck in the gears.

It did spark a debate whether there should be two statuses, Withdrawn and Abandoned, or one. This is clearly explained [in this recent issue](https://github.com/ethereum/EIPs/issues/2941).

And a wording suggestion, Living to replace Active, was proposed on the call, which while may not be the best, it seems to be better than Active.

## Hard forks

I have [favoured splitting](https://github.com/ethereum-cat-herders/EIPIP/blob/master/All%20EIPIP%20Meetings/Meeting%20008.md#5-separation-of-eip-process-and-hard-fork-coordination) the hardfork management and the specification management proccesses. It seems now a lot of people think alike. As explained this allows for a great simplification and hopefully much more smoother process.

Based on updates on the ACD calls it seems there is a [eth1.0-specs](https://github.com/ethereum/eth1.0-specs) repository now to track and manage proposals as well as test rollouts on the so called ["YOLO" ephemeral testnets](https://eips.ethereum.org/EIPS/eip-2657).

Even when the last remnants of the hard fork process are removed from the EIP repository, I think the original idea of EIP-233 still makes sense: to document an existing hard fork in a meta document (in the same place, where the change specifications are).

However this original idea of EIP-233 was expanded on, and the rules changed to create a meta document as early as possible to ensure the fork's name is clear, because different clients used different names. This is a not a problem anymore as a [naming scheme was agreed on](https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2068.md#decisions-made).

And finally it was extended again with some process to track forks during their planning and coordination. Luckily this is going to be handled by eth1.0-specs.

These "hard fork metas", as they are colloquially known, have proven to be a very useful resource for documenting hard forks after they have taken place.

## Proposed Process

Since we should be standing on the shoulder of giants, arguably one of the better resources to look up are the [RFC process](https://www.rfc-editor.org/pubprocess/) and the [W3C process](https://www.w3.org/2014/Process-20140801/). While they deal with much larger specifications than what EIPs usually are, I think we can learn from them.

digraph EIP1 {
#rankdir=LR
concentrate=true

Idea -> Draft; 
Draft -> Candidate;
Draft -> Withdrawn;
Candidate -> Draft;
Candidate -> Withdrawn;
Candidate -> Proposed;
Proposed -> Candidate;
Proposed -> Withdrawn;
Proposed -> Final;
Withdrawn -> Draft;
Proposed -> Living;

Living [label="Living or Active"];
Candidate [label="Candidate or Review"]
Proposed [label="Proposed or Last Call"];
}

Here I have borrowed the terms from W3C, which I would prefer, but could live with the alternatives listed above, which follow already existing or proposed terms. I have a slight preference for Candidate though.

### Idea

An idea should be vetted before submitting a pull request (PR) for creating a daft. It can be vetted on [Ethereum Magicians](https://ethereum-magicians.org), [ethresear.ch](https://ethresear.ch), and various Gitter or Discord channels.

### Draft

Once there is some interest in an idea, a draft following the EIP template should be created. If the draft passes basic syntax requirements it should be merged.

**Question**: There are various views on how much vetting an editor can do here -- unclear. If we have a well working process of removing unsuccessful EIPs, then early merging drafts without question is the correct way.

During this stage it is expected that the draft is discussed at least by a smaller group of interested participants.

There is no time restriction on this status, but it is encouraged to keep this within "reasonable" bounds, i.e. a few months. It is very discouraged keeping something as a draft for years.

### Candidate (or Review)

Once the draft is sufficiently stable and no major changes are expected, it should be moved to this stage.

This is the phase to reach out to a larger number of participants to gather more feedback. Since these participants can reasonably expect the specification will not change overnight, they are more likely to commit their time for reviews and discussions.

This phase should last at least 45 days to allow for feedback.

### Proposed (or Last Call)

Once the participants feel the specification is reasonably stable and there is no expectation of changes, it should be moved to this stage.

This is the phase to do a final push and ask for feedback before the specification is finalised and no more changes are possible. (Apart from errata -- see below.)

This phase should last at least 14 days.

Should small changes come up they can be fixed without a change in status, otherwise it must be reverted back to Candidate.

*Special requirement*: a `review-end-date` field must be present in the frontmatter.

### Final

If a Proposed specification was successful it would end up here.

### Withdrawn

It is possible moving to this status from any, except Final and Living.

*Special requirement:* a `reason` field must be present with one of the following options:
- `withdrawn by author`: if it was a decision by the author, during any of the stages
- `withdrawn due to inactivity`: if there was no activity from the author for a specified length of time (180 days)
- ~~-`replaced by EIP-N`: if it was a decision by the author, and a new EIP is recommended~~

### Living (or Active)

The special EIP-1 and EIPs operating as a registry are marked this status, because they are never considered to be finalised.

Any new registry document must go through the entire EIP process, before becoming Living.

### Archived

While not a status, it would be a way to remove long-Withdrawn EIPs (more than 730 days) from "cluttering" the repository. The idea is [described here](https://github.com/ethereum/EIPs/issues/2962).

### Obsolete

While not a status, the obsoletion process is borrowed from RFCs. Two fields are introduced:
- `obsoleted-by`: contains a single EIP number which obsoletes this EIP
- `obsoletes`: contains a list of EIP numbers which are obsoleted by this EIP

The `obsoleted-by` field can be present only on Final or Withdrawn statuses.

The `obsoletes` field can only be present as long as the referenced EIP's `obsoleted-by` field points back.

This means the author of both the obsoleting and obsoleted EIPs must come to an ageement. It may be possible to relax this in the future, given a better process is proposed for obsoletion.

### Errata

As customary, small typographical fixes can be applied by the disrection of editors.

Any change clarifying the specification should be possible given it is a small fix which can be explained in section called `Errata`. If the fix is fundamental, the EIP must be obsoleted and a new EIP must be created.

### Remarks

The following frontmatter fields are removed, because they are not specified well and/or unused:
- `replaces` (replaced by obsoletion)
- `superseded-by` (replaced by obsoletion)
- `resolution`

They can be added back when there is a need.

The following statuses are removed:
- Abandoned ([renamed to Withdrawn](https://github.com/ethereum/EIPs/issues/2941))
- Rejected
- Accepted
- Superseded (replaced by obsoletion)

## Tools

The biggest challenge with EIPs however is the manual labour it requires.

Recently the old formatting validator – [eip_validator](https://github.com/makoto/eip_validator) – was replaced with a much more competent version: [eipv](https://github.com/lightclient/eipv). Additionally we have turned on a [bot to check for stale issues](https://github.com/ethereum/EIPs/pull/2949).

Despite these there is still a lot of manual work required by the editors and reviewers, and if we aim to have a smooth process, most of it should be replaced with bots. I have created a [new issue to track the bots we need](https://github.com/ethereum/EIPs/issues/2961) on the EIP repository.

Any volunteers interested in implementing them? :grimacing: