EIP editor "apprentice" handbook

--- tags:EIP --- # 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. ## 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](https://github.com/ethereum/EIPs) 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.](https://github.com/ethereum/EIPs/pull/5207#issuecomment-1178626743) **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](https://www.ethereumcatherders.com/) 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](https://medium.com/ethereum-cat-herders/the-new-ethereum-improvement-process-928c628b306e) & [network upgrade process](https://medium.com/ethereum-cat-herders/shedding-light-on-the-ethereum-network-upgrade-process-4c6186ed442c), 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](https://eips.ethereum.org/EIPS/eip-1). If you aspire to be an editor, you may also start looking into Issues & Pull Requests at [**EIPs GitHub**](https://github.com/ethereum/EIPs). Read the proposals, participate in active discussion, leave your comments to the pull request with improvement suggestions (if any). Follow the [monthly **EIPs Insight**](https://hackmd.io/@poojaranjan/EthereumImprovementProposalsInsight) to keep track of upcoming Ethereum Improvement Proposals. Among other resources, ECH produces [PEEPanEIP video series](https://www.youtube.com/playlist?list=PL4cwHXAawZxqu0PKKyMzG_3BJV_xZTi1F) 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](https://github.com/ethereum/EIPs/blob/master/.github/workflows/auto-merge-bot.yml#L20-L26) 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](https://github.com/ethereum/EIPs) repository. Once merged, another pull request to update [EIP-1](https://eips.ethereum.org/EIPS/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.