EIP 1 Update: New Changes to EIP Process #183
Conversation
|
using PR numbers seems like a good idea to me |
EIPS/eip-1.mediawiki
Outdated
|
|
||
| Vetting an idea publicly before going as far as writing a EIP is meant to save the potential author time. Asking the Ethereum community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Ethereum is used. | ||
| Vetting an idea publicly before going as far as writing a EIP is meant to save the potential author time. Asking the Ethereum community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Ethereum is used. Examples of appropriate public forums to gauge interest around your EIP include [https://www.reddit.com/r/ethereum/ the Ethereum subreddit] and [https://gitter.im/ethereum/ one of the Ethereum Gitter chat rooms]. |
There was a problem hiding this comment.
Any standards for where to put these pre-draft EIPs and what to call them? Currently we open an issue in the EIP repository and refer to it by issue number, and by watching there you get some warning of what's coming. Do we keep doing that? With with no place for them in the workflow I fear reversion to chaos. It becomes "That proposal of John's that he posted on Reddit last week. I think there is a newer version on his blog. No, not that proposal, the other one, I forget the title..." rather than a link to the usual place from wherever it is being discussed.
There was a problem hiding this comment.
I suggest borrowing a page from RFCs; drafts can be written and submitted in a separate directory named eip-draft-some-short-name; they're only given a number an made standards when consensus is reached and the editor approves the move.
There was a problem hiding this comment.
OK. I have a proposal ready for the old place today. I don't know what to do with it now. Seems we are taking a social practice that was working, and technically supported by github, and abandoning it.
There was a problem hiding this comment.
So your suggestion is OK if we must, but we need to get from here to there fast.
There was a problem hiding this comment.
I really don't think the current process is working. There's no clear indication of which EIPs are in which phase, and the original issue often doesn't reflect the actual standard, because only the creator of an issue can edit the top post - making each EIP submitter the benevolent-dictator-for-life of the EIP they submitted.
There was a problem hiding this comment.
It primarily preserves the revision history of the EIP, but by finding the associated PR, you can find the comments associated with each set of changes.
Personally, I'm less concerned about easily finding discussions on past EIPs than I am about having a clear revision history of the standard itself.
There was a problem hiding this comment.
Btw, here is a diagram of my proposal to change the process:
Compared to the current diagram:
There was a problem hiding this comment.
Thinking about it more, here is my ideal process wrt discussion of EIPs.
- PR made with initial thoughts.
- Template should be used, but upon first submitting PR, you should only fill in what your idea is and leave the sections you cannot fill out blank. So drafts of the idea are in the PR.
- As people discuss the idea in the PR, the draft is updated until it is successfully formalized and the status is switched from "Draft" to either "Accepted" or "Rejected" depending on consensus (which is judged by the editors and in the future Ethereum based signaling methods/contracts).
- Once the state is switched to Final, it is added to the README EIP list.
- The EIP being added may trigger another EIP to be listed as "Replaced" if the new EIP substantially modifies a previous EIP.
There was a problem hiding this comment.
New diagram (everything occurs as a PR in the EIP GitHub
There was a problem hiding this comment.
The additional benefit of the diagram above is that numbering can be on an EIP level since all EIPs are created and discussed in a PR. Even ones that are rejected or don't make it should be numbered so they can be referenced in future EIPs.
|
For numbering and drafts, can we borrow a page from RFCs? Have a drafts directory, with named rather than numbered EIPs - EIP-draft-some-short-title.md. Make the approval process for a draft PR simpler than that for a final one, and only assign it a number (the next one sequentially) when transitioning from draft to final. |
EIPS/eip-1.mediawiki
Outdated
| ** Core - improvements requiring a consensus fork (e.g. [https://github.com/ethereum/EIPs/blob/master/EIPS/eip-5.md EIP5], [https://github.com/ethereum/EIPs/issues/28 EIP101]), as well as changes that are not necessarily consensus critical but may be relevant to “core dev” discussions (for example, [https://github.com/ethereum/EIPs/issues/90 EIP90], and the miner/node strategy changes 2, 3, and 4 of [https://github.com/ethereum/EIPs/issues/86#issue-145324865 EIP86]). | ||
| ** Networking - includes improvements around [https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol devp2p] ([https://github.com/ethereum/EIPs/blob/master/EIPS/eip-8.md EIP8]) and [https://github.com/ethereum/wiki/wiki/Light-client-protocol Light Ethereum Subprotocol], as well as proposed improvements to network protocol specifications of [https://gist.github.com/gluk256/4654922ca45eb9d0846d941d7ca326f4 whisper] and [https://github.com/ethereum/go-ethereum/pull/2959 swarm]. | ||
| ** Interface - includes improvements around client [https://github.com/ethereum/wiki/wiki/JSON-RPC API/RPC] specifications and standards, and also certain language-level standards like method names ([https://github.com/ethereum/EIPs/issues/59 EIP59], [https://github.com/ethereum/EIPs/blob/master/EIPS/eip-6.md EIP6]) and [https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI contract ABIs]. The label “interface” aligns with the [https://github.com/ethereum/interfaces interfaces repo] and discussion should primarily occur in that repository before an EIP is submitted to the EIPs repository. | ||
| ** ERC - application-level standards and conventions, including contract standards such as token standards ([https://github.com/ethereum/EIPs/issues/20 ERC20]), name registries ([https://github.com/ethereum/EIPs/issues/26 ERC26], [https://github.com/ethereum/EIPs/issues/137 ERC137]), URI schemes ([https://github.com/ethereum/EIPs/issues/67 ERC67]), library/package formats ([https://github.com/ethereum/EIPs/issues/82 EIP82]), and wallet formats ([https://github.com/ethereum/EIPs/issues/75 EIP75], [https://github.com/ethereum/EIPs/issues/85 EIP85]). |
There was a problem hiding this comment.
This is long overdue - thanks! Informational was really not the right tag for these.
There was a problem hiding this comment.
@cdetrio came up with all of this. He is to thank :)
EIPS/eip-1.mediawiki
Outdated
| * An Informational EIP describes a Ethereum design issue, or provides general guidelines or information to the Ethereum community, but does not propose a new feature. Informational EIPs do not necessarily represent Ethereum community consensus or a recommendation, so users and implementors are free to ignore Informational EIPs or follow their advice. | ||
| * A Meta EIP describes a process surrounding Ethereum or proposes a change to (or an event in) a process. Process EIPs are like Standards Track EIPs but apply to areas other than the Ethereum protocol itself. They may propose an implementation, but not to Ethereum's codebase; they often require community consensus; unlike Informational EIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Ethereum development. Any meta-EIP is also considered a Process EIP. | ||
|
|
||
| ==EIP Work Flow== | ||
|
|
||
| The EIP repository Collaborators change the EIPs status. Please send all EIP-related email to the EIP Collaborators, which is listed under EIP Editors below. Also see EIP Editor Responsibilities & Workflow. | ||
|
|
||
| The EIP process begins with a new idea for Ethereum. It is highly recommended that a single EIP contain a single key proposal or new idea. Small enhancements or patches that don't affect consensus often don't need a EIP and can be injected into the Ethereum development workflow with a patch submission to the corresponding Ethereum issue tracker. The more focused the EIP, the more successful it tends to be. The EIP editor reserves the right to reject EIP proposals if they appear too unfocused or too broad. If in doubt, split your EIP into several well-focused ones. | ||
| The EIP process begins with a new idea for Ethereum. It is highly recommended that a single EIP contain a single key proposal or new idea. Small enhancements or patches often don't need an EIP and can be injected into the Ethereum development workflow with a patch submission to the corresponding Ethereum issue tracker. The more focused the EIP, the more successful it tends to be. The EIP editor reserves the right to reject EIP proposals if they appear too unfocused or too broad. If in doubt, split your EIP into several well-focused ones. |
There was a problem hiding this comment.
Since you're editing this bit anyway, instead of talking about how big the change is, it probably makes sense to distinguish changes based on whether they require coordination. A change to one client doesn't require an EIP; a change that affects multiple clients, or defines a standard for multiple apps to use, does.
EIPS/eip-1.mediawiki
Outdated
|
|
||
| Vetting an idea publicly before going as far as writing a EIP is meant to save the potential author time. Asking the Ethereum community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Ethereum is used. | ||
| Vetting an idea publicly before going as far as writing a EIP is meant to save the potential author time. Asking the Ethereum community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Ethereum is used. Examples of appropriate public forums to gauge interest around your EIP include [https://www.reddit.com/r/ethereum/ the Ethereum subreddit] and [https://gitter.im/ethereum/ one of the Ethereum Gitter chat rooms]. |
There was a problem hiding this comment.
I suggest borrowing a page from RFCs; drafts can be written and submitted in a separate directory named eip-draft-some-short-name; they're only given a number an made standards when consensus is reached and the editor approves the move.
EIPS/eip-1.mediawiki
Outdated
| ==EIP Formats and Templates== | ||
|
|
||
| EIPs should be written in mediawiki or markdown format. Image files should be included in a subdirectory for that EIP. | ||
| EIPs should be written in [https://en.wikipedia.org/wiki/Help:Cheatsheet mediawiki] or [https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet markdown] format. Image files should be included in a subdirectory for that EIP. |
There was a problem hiding this comment.
Could we just drop mediawiki support? It's much harder to parse, and isn't compatible with systems like Jekyll.
There was a problem hiding this comment.
But markdown is so very, very lame ;->
There was a problem hiding this comment.
That's nothing compared to MediaWiki. Parsing MW markup is, believe it or not, turing complete, because you cannot parse it without the set of plugins that it was written for. In fact, mediawiki doesn't really have a parser - it has a list of regular expression search-and-replace operations.
There was a problem hiding this comment.
Aaargh... I think I may go back to plain ASCII text - display with fixed width font or else. Format as I please.
There was a problem hiding this comment.
The argument for mediawiki was that it has better math notation support. However, github currently doesn't render math, so it seems moot.
There was a problem hiding this comment.
Sigh. It's so nice in 2016 to be using text formatting facilities that are more primitive than the ones I used in 1976. Progress.
There was a problem hiding this comment.
I am in favor of removing mediawiki support and having GitHub flavored markdown as the only format accepted. I have re-written EIP1 in markdown.
|
I think for issues one can create templates, we should do the same for PR's so the format is already clear. |
But if our intention is to reduce the number and quality of submitted EIP drafts and obscure their provenance, by all means. |
|
Good points Greg. Really the numbering doesn't really matter, it is primarily the updating of the "official" EIP once it is near finalized. For example: An EIP can be "Finalized" and added to the list and linked to the issue number. If the author of that EIP wants to, they can go back after the fact and change the details of their EIP undetected. The reason to move to PRs is primarily to keep tabs on the iterations of the templated EIP and not necessarily discussion. In the future when we use signaling methods on the blockchain to show consensus around EIPs it will be important to have that data separate from the discussion and inside of a PR. All that being said, I think there is a middle ground where issues are for discussions/numbering and PRs are for determining consensus/changing the status to accepted. Imo even though making PRs is more difficult than issues, for formalizing EIPs it is necessary for us to have that history of EIP changes once it is formalized. |
|
I don't understand, "If the author of that EIP wants to, they can go back after the fact and change the details of their EIP undetected." That's only true in the issue phase, I thought. Once there is a Draft PR every change requires a commit, no? I agree, and think I've been asking all along that, "issues are for discussions/numbering and PRs are for determining consensus/changing the status to accepted... for formalizing EIPs it is necessary for us to have that history of EIP changes ..." |
But literally every EIP is in this state except for the first 5. Opening issues was never a part of the formal process, it was a response to a broken system - and it is itself broken.
They're harder to create than an issue, but not much harder. You can even do it entirely, end to end, in the GitHub UI if you want. And I don't think putting a small barrier in front of people wanting to introduce new standards is a big problem. The comment machinery is almost exactly identical to that in issues, except it also allows commenting on individual lines, which issues don't.
Currently, there's no distinction as to the status of an EIP; people refer to EIP issues as if they're finalised standards. |
You are correct, and in that quoted statement I was referring to GH issues and how they are non-permanent. I think the confusion was that when you said So it sounds like based on your feedback you would be in favor of this diagram: |
|
Not quite, Hudson. I'm not sure why Draft and the rest are on the "Issues" side of the line. A Draft requires a PR in Github, an Issue does not. Nick, of the over a hundred issues under discussion a handful got pushed through to Accepted with no public process. That should not have happened even under the current scheme. That doesn't mean that issues are broken, it means whoever had permissions to merge to the repo should not have. Or are issues broken in some other way I don't get? And yes, it isn't that hard to create a PR, (unless you have wait for a editor to approve it, and meet their standards first.) And we can have a warning up front like "Do NOT open issues. Open a PR." I don't know if we can actually lock down the Issues. And I don't know if we want the repo clogged up with a hundred PRs that go nowhere. I think most people get that having an EIP number isn't the same thing as being accepted. (Switching to PRs still means numbers get assigned before EIPs are accepted.) Having a much more transparent process for getting to Accepted should make that even more clear. And again, I don't want to kill an imperfect existing practice with little assurance that we won't just make things worse. |
|
I put Drafts in the Issue side based on your earlier comment: "I agree, and think I've been asking all along that, "issues are for discussions/numbering and PRs are for determining consensus/changing the status to accepted... for formalizing EIPs it is necessary for us to have that history of EIP changes ...":" That made me think that you wanted the entire discussion and rough drafting of the EIP to occur in the "Issues" section as it does now and then to better enforce a formal EIP PR to determine consensus and acceptance/rejection once the issue discussion is finished. |
I agree. Many potential EIPs could be practical ideas from folks with lesser programming expertise. As is done by you all with the platform itself, simpler == more reliable / efficient. |
Do you mean EIPs 1-5? Those are the only EIPs that have ever been accepted according to the current protocol, and that seems like a far bigger problem with the process than that those few EIPs might not have got enough discussion.
I see references to, say, EIP20, all over the place, as if it's a finalised standard (which it probably should be by now, but isn't).
I don't mean to sound unduly harsh, but EIPs are not the place for brainstorming like this; EIPs need to be well defined and specific. |
|
I think the main thing @taoteh1221 and @gcolvin is looking for is a better/alternative place people would go if we take away the issues section for EIP discussion. In their opinion it is both a social convention at this point and a path for the less technical to participate, which I agree with. However, I think the real enforcement needs to begin on the "not official until a PR is made" point. I plan on going through and requesting formal PRs be submitted for all "accepted" or "almost accepted" issues that have becomes PRs, such as 150 and ERC20 v1 spec. So as long as we explicitly say that issues are only for discussion and there is an updated EIP1 to define stricter formal EIP acceptance that is enough. We can stay on top of enforcement and retroactively create PRs with the EIPs from the HF that have been approved. |
|
I'm still concerned that the failure mode of this is to return to what we have now - eg, issues are defacto EIPs - and that it will be difficult to communicate to people that this is no longer the case (eg, they'll continue to link to issues as EIPs). It really seems like you ought to be able to have the same sort of discussion on a PR as you can have on an issue, only that way it has a clearly defined endpoint. |
|
I do share share your concern, Nick. It's just that the trains have long since left the station. We can't stop people from using EIP issues without wiping away all existing issues, but we absolutely can stop promoting mere issues to Accepted status with no PR and no accepted process. We also can't change the Github and Gitter abbreviation conventions for Issues links, and the confusion they engender. What we can do is make very clear that nothing short of an Accepted EIP is binding. We can and should discourage using issues for just any idea - there are many other channels for that. But there is a range of ideas that are intended to become EIPs if they work out, are too big for the scattershot discussions that channels foster, but not are ready for a draft proposal. EIP issues have become the place where we discuss those, and link to them for discussion in more ephemeral channels. |
|
Issues that were decided on other comms channels:
Todo:
New graph to reflect changes. Please comment to correct anything above and to help finish out the todos. I hope to implement the changes asap. |
|
I think it should mandatory for EIPs (at least for precompiles) to include test cases. |
|
For EIPs that affect the consensus, I agree. There are a lot of ERCs for which that doesn't apply, though. |
|
🤔
…On Wed, 25 Jan 2017 at 14:41, Nick Johnson ***@***.***> wrote:
For EIPs that affect the consensus, I agree. There are a lot of ERCs for
which that doesn't apply, though.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#183 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/ABbxullKuEm3ubT8YMLLQafegsbNuLzYks5rV18ogaJpZM4LHV8e>
.
|
|
I have deleted the mediawiki version and uploaded the .md version. New graph is added. Last thing we have to confirm is templates: I like them and have no issues. We will take feedback for a bit and then launch overhaul. We can always tweak the template after setting the new rules in place if we run into an inconsistency. |
|
Thinking about it, I will go ahead and merge this so we can get the new templates up (even if we need to update them in the next 24 hours or make small corrections to README). |
|
Just read the PR draft on HackMD. For many proposals it still seems a Procrustean bed. Need there be both a Summary and an Abstract? Need there be both a Motivation and a Rationale? And what about proposals that interleave specification and rationale? I could do with a simpler template, or a least some indication that it's not a rigid set of requirements but a strong suggestion. |
|
@gcolvin the template sections are just suggestions, not rigid requirements. It says at the top "suggested template". |
|
OK. |
|
please ignore my last question, I have since found the answer. |
[Updated 1/25/2016]
Outline of changes/clarifications
Undecided
Future Goals