EIP editor "apprentice" handbook

An Ethereum Improvement Proposal (EIP) is a design document providing information to the Ethereum community, or describing a new feature for Ethereum or its processes or environment. Ethereum Request for Comments (ERCs) are Standard Track EIPs, which are application-level standards and conventions.

The EIP/ERC (standardization) process is a primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Ethereum. Because improvement proposals are key components of Ethereum blockchain, it is important that they are well reviewed before reaching FINAL status.

EIPs are stored in text files in a versioned repository which is monitored by the EIP/ERC editors.

Guidelines from an EIP Editor for reviewing a proposal.

Responsibilities of an editor

An editor's responsibility includes monitoring, and ensuring the fairness, timeliness, thoroughness of an improvement proposal before it is merged to the EIPs GitHub repository. On a high-level, an EIP or ERC editor is responsible

• to ensure relevance - any new proposal submitted is related to Ethereum blockchain.
• to review the proposal - to check a new proposal for it's readiness to ensure that
  • the title describing the content is accurate,
  • idea making sense technically,
  • language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), code style and
  • the proposal is well formatted.
    If the proposal is not ready, the editor will leave a comment with specific instructions to improve or reject the proposal.
• to assign an EIP number - once a proposal is ready for the EIP GitHub repository, the editor will assign an EIP number, generally the PR number. In rare cases to discourage sqautting, an unused EIP number may also be provided to the proposal.
• to merge the draft - with the EIP number added, the corresponding pull request is merged with DRAFT status.

At present EIP-1 describes that a proposal needs to be in Last call for (at least) 14 days. No specific instructions of what to be done next in different situations.

Exceptional cases

Q. What are the guidelines to request a status change of an EIP from Stagnant.

A. It's up to the author to bring it back to the status as he/she finds appropriate, starting from Draft and it could be the original status from where it was moved to Stagnant.

• Ideally it wouldn't require EIP editors' permission and it should be automerged by the eip-bot.
• A proposal can be in the Stagnant status forever. If it comes to that,Stagnant status be considered as terminal status for a proposal.
• If a proposal needs to be moved to Final status and the author is not around to make changes suggested by EIP editor or champion the porposal, an EIP champion can be added to the proposal as co-author. It can be an 'EIP editor apprentice' or anyone from community volunteering to work with EIP editors to push the proposal through.
  Alternatively, a new EIP with the same text of the earlier proposal and author as co-author(s) can be created to move the proposal to the Final status.

Note: Stagnant EIPs shouldn't be receiving updates. If you are the author and want to pick this EIP back up and move it through the process toward review then please create a PR to move it out of stagnant and into Draft or Review. If you are not the author but you want to champion this idea, you can either try to contact the author to get them to add you to the authors list or you can create a new EIP (feel free to copy the contents). Ref.

Q: Is it okay for an author to ignore any improvement suggestions received during the Last Call period and continue moving the proposal to Final?

A: Yes, it is up to the author to accept or reject any improvement suggestions received on the proposal at any stage of the EIP standardization process. However, if the user making the comment or suggesting changes is not happy with the proposal being moved towards standardization in current form, he/she is may submit a new proposal.

Q: What if an author creates a pull request to promote an EIP from Review to Last Call and becomes unavialble for next 14 days to address any comments by editors/community before the proposal is actually merged?

A: In case of compliance issue, the proposal will not be merged unless appropriate response is received. Also, the Last Call end date will be updated as per the date of merge of the proposal. In any other case, editor does not have a say.

Q: Can a proposal be moved to Final if approved by author?

A: A proposal moving to Final, needs approval of at least one EIP editor. It can not be auto-merged by the author's approval.

Q: Can author/anyone propose changes after a proposal is merged as Final?

A: A Final EIP may accept non-normative changes, however, it is best to avoid making any changes to a Final proposal.

Q: What if author isin't sure what is the best EIP "Type" or "Category" for the documentation of the proposal?

A: Proceed with the best judgement at the time. EIP "Type" and "Category" can be changed later on.

Q: Is Test Cases section mandatory?
A: Test Cases section is optional and part of the reason for that is so people don't have to make sure have test cases ready at the beginning. So whenever you have test cases ready add them in, if you don't have them then just leave the section out entirely.

Q: Is there a policy to merge a pull request in absence of author's availability?
A: If a pull request is approved by at least one EIP editors and been sitting for months with a trivial grammer or spelling change or typo or minor bug. At that point any of the EIP editor may override for editorial edits and merge that. EIP bot can also enable this merge.

Editors do the administrative & editorial part and don’t pass judgment on the proposal.

Frequently Asked Questions

What is an EIP/ERC editor mentorship program?

This is an initiative by the Ethereum Cat Herders to attract potential talent of the community to accelerate & improve the standardization process.

The process includes completing the editorial tasks in the guidance of experienced editors for inital 3 months as EIP editor (Trainee). The goal here is to provide support while a trainee educates himself with the process and is ready to work independently.

Who can apply?

Any contributor of Ethereum ecosystem having a good understanding of EIP/ERC standardization & network upgrade process, intermediate level experties on core and/or application side of the Ethereum blockchain and the willingness to contribute to the process managementcan be EIP/ERC editor. Other than being a good communicator and be able to handle contentious discourse, an editor must be able to commit 1-5 hrs. per week.

Where can I start?

The best available resource to understand the EIP/ERC & processes around it is EIP-1: EIP Purpose and Guidelines. If you aspire to be an editor, you may also start looking into Issues & Pull Requests at EIPs GitHub. Read the proposals, participate in active discussion, leave your comments to the pull request with improvement suggestions (if any). Follow the monthly EIPs Insight to keep track of upcoming Ethereum Improvement Proposals. Among other resources, ECH produces PEEPanEIP video series for a quick overview of these proposals.

How can an apprentice make a request to be formally onboarded as an EIP editior?

The contribution of an apprentice will be monitored by all EIP editors during the internship period. After 6 months of reviewing the pull requests as apprentice, when the contributor feels comfortable enough with the process and would like to be added to the repository as an EIP editor, a pull request with request to be listed as EIP editor has to be made.

This will enable the contributor to get notifications of new proposals submitted at EIPs repository, enable to merge pull requests and/or when EIP editor is invited for review by authors.

The pull request will be reviewed by the existing editors. If the PR receives approval from a majority of existing EIP editors, then it will be merged to the EIP GitHub repository.

Once merged, another pull request to update EIP-1 to be listed as active EIP editor has to me made.

Will editor be paid?

Historically, EIP/ERC editing has been done by the volunteers of the Ethereum community. Recently, Ecosystem Support Program provided a grant to the Ethereum Cat Herders to work with the present editors and individual applicants and provide a “stipend” amount to invite more community participation.