Skip to content

Latest commit

 

History

History
210 lines (135 loc) · 19.1 KB

nep-0001.md

File metadata and controls

210 lines (135 loc) · 19.1 KB
Raw
NEP Title Authors Status DiscussionsTo Type Version Created Last Updated
1
NEP Purpose and Guidelines
Bowen W. <bowen@near.org>, Austin Baggio <austin.baggio@near.org>, Ori A. <ori@near.org>, Vlad F. <frol@near.org>;
Approved
Developer Tools
1.1.0
2022-03-03
2023-03-05

Summary

A NEAR Enhancement Proposal (NEP) is a design document that specifies reusable and interoperable components integrated across the NEAR ecosystem.

NEPs are the primary mechanism for evolving NEAR’s runtime, Smart Contract Standards, and Wallets ecosystem in a community-driven way. NEPs provide a concise technical specification and a rationale for the feature. The NEP author is responsible for building consensus within the community and documenting dissenting opinions. The typical primary audience for NEPs are the developers of the NEAR reference implementations and decentralized application developers.

NEPs are stored as text files in a versioned repository, allowing for easy historical tracking. A list of NEPs is available on GitHub.

Motivation

The purpose of the NEP process is to ensure the seamless evolution of the NEAR platform and to empower the community to contribute to its development. Given the complexity and number of participants involved across the ecosystem, a well-defined process helps ensure transparency, security, and stability.

NEP Types

There are four kinds of NEPs:

  1. A Protocol NEP describes a new feature of the NEAR protocol.
  2. A Contract Standards NEP specifies NEAR Smart Contract interfaces for a reusable concept in the NEAR ecosystem.
  3. A Wallet Standards NEP specifies ecosystem-wide APIs for Wallet implementations.
  4. A Developer Tools NEP defines norms and guidelines for developer tooling in the NEAR ecosystem.

Currently, all types of NEPs follow the same process, but for Protocol NEPs a draft implementation is required.

Submit a NEP

Start with ideation

Everyone in the community is welcome to propose, discuss, and review ideas to improve the NEAR protocol and standards. The NEP process begins with a new idea for the NEAR ecosystem. A single NEP should contain a single key proposal or new idea.

Each NEP must have an author: Someone who writes the NEP using the style and format described below. The author, or another champion, shepherds the discussions in the appropriate forums and attempts to build community consensus around the idea to help it progress toward completion.

Before submitting a NEP, the author should first attempt to ascertain whether the idea is NEP-able. Vetting an idea publicly before writing a NEP saves the potential author time. Asking the NEAR community first if the idea is original helps prevent effort on something guaranteed to be rejected based on prior discussions. It also helps ensure the idea applies to the entire community. Just because an idea sounds good to the author does not mean it will work for most people in most use cases.

In general, the process for socializing an idea is:

  • Check prior proposals: Many ideas for changing NEAR come up frequently. Please search the Dev Gov Gigs Board, the NEAR Forums, and NEPs in this repo before proposing something new.
  • Share the idea: Submit your idea on the Dev Gov Gigs Board.
  • Get feedback: The Dev Gov Gigs Board has comment threading which allows the community to ideate, ask questions, wrestle with approaches, etc. If more immediate responses are desired, consider bringing the conversation to the appropriate Community Group.

Submit a NEP Draft

Following the above initial discussions, the author should submit a NEP draft into the GitHub NEP repository. The draft NEP must follow the NEP-0000 template, or else it will fail the review immediately.

To submit a NEP draft as a pull request, the NEP author should:

  1. Fork the NEPs repository.
  2. Copy nep-0000-template.md to neps/nep-0000-my-feature.md (where “my-feature” is descriptive; don’t assign a NEP number yet).
  3. Fill in the NEP following the NEP template guidelines. For the Header Preamble, make sure to set the status as “Draft.”
  4. Push this to your GitHub fork and submit a pull request.
  5. Now that your NEP has an open pull request, use the pull request number to update your 0000 prefix. For example, if the PR is 305, the NEP should be neps/nep-0305-my-feature.md.
  6. Push this to your GitHub fork and submit a pull request. Mention the @near/nep-moderators in the comment and turn the PR into a "Ready for Review" state once you believe the NEP is ready for review.

NEP Lifecycle

The NEP process begins when an author submits a NEP draft. The NEP lifecycle consists of three stages: draft, review, and voting, with two possible outcomes: approval or rejection. Throughout the process, various roles play a critical part in moving the proposal forward. Most of the activity happens asynchronously on the NEP within GitHub, where all the roles can communicate and collaborate on revisions and improvements to the proposal.

NEP Process

NEP Stages

  • Draft: The first formally tracked stage of a new NEP. This process begins once an author submits a draft proposal and the NEP moderator merges it into the NEP repo when properly formatted.
  • Review: A NEP moderator marks a NEP as ready for Subject Matter Experts Review. If the NEP is not approved within two months, it is automatically rejected.
  • Voting: This is the final voting period for a NEP. The working group will vote on whether to accept or reject the NEP. This period is limited to two weeks. If during this period necessary normative changes are required, the NEP will revert to Review.

Moderator, when moving a NEP to review stage, should update the Pull Request description to include the review summary, example:

---

## NEP Status _(Updated by NEP moderators)_

SME reviews:

- [ ] Role1: @github-handle
- [ ] Role2: @github-handle

Contract Standards WG voting indications (❔ | :+1: | :-1: ):

- ❔ @github-handle
- ❔ ...

<Other> voting indications:

- ❔
- ❔

NEP Outcomes

  • Approved: If the working group votes to approve, they will move the NEP to Approved. Once approved, Standards NEPs exist in a state of finality and should only be updated to correct errata and add non-normative clarifications.
  • Rejected: If the working group votes to reject, they will move the NEP to Rejected.

NEP Roles and Responsibilities

author Author
Anyone can participate

The NEP author (or champion) is responsible for creating a NEP draft that follows the guidelines. They drive the NEP forward by actively participating in discussions and incorporating feedback. During the voting stage, they may present the NEP to the working group and community, and provide a final implementation with thorough testing and documentation once approved.

Moderator Moderator
Assigned by the working group

The moderator is responsible for facilitating the process and validating that the NEP follows the guidelines. They do not assess the technical feasibility or write any part of the proposal. They provide comments if revisions are necessary and ensure that all roles are working together to progress the NEP forward. They also schedule and facilitate public voting calls.

Reviewer NEP Reviewer (Subject Matter Experts)
Assigned by the working group

The reviewer is responsible for reviewing the technical feasibility of a NEP and giving feedback to the author. While they do not have voting power, they play a critical role in providing their voting recommendations along with a summary of the benefits and concerns that were raised in the discussion. Their inputs help everyone involved make a transparent and informed decision.

Approver Approver (Working Groups)
Selected by the Dev Gov DAO in the bootstrapping phase

The working group is a selected committee of 3-7 recognized experts who are responsible for coordinating the public review and making decisions on a NEP in a fair and timely manner. There are multiple working groups, each one focusing on a specific ecosystem area, such as the Protocol or Wallet Standards. They assign reviewers to proposals, provide feedback to the author, and attend public calls to vote to approve or reject the NEP. Learn more about the various working groups at neardevgov.org.

NEP Communication

NEP discussions should happen asynchronously within the NEP’s public thread. This allows for broad participation and ensures transparency.

However, if a discussion becomes circular and could benefit from a synchronous conversation, any participants on a given NEP can suggest that the moderator schedules an ad hoc meeting. For example, if a reviewer and author have multiple rounds of comments, they may request a call. The moderator can help coordinate the call and post the registration link on the NEP. The person who requested the call should designate a note-taker to post a summary on the NEP after the call.

When a NEP gets to the final voting stage, the moderator will schedule a public working group meeting to discuss the NEP with the author and formalize the decision. The moderator will first coordinate a time with the author and working group members, and then post the meeting time and registration link on the NEP at least one week in advance.

All participants in the NEP process should maintain a professional and respectful code of conduct in all interactions. This includes communicating clearly and promptly and refraining from disrespectful or offensive language.

NEP Playbook

  1. Once an author submits a NEP draft, the NEP moderators will review their pull request (PR) for structure, formatting, and other errors. Approval criteria are:
    • The content is complete and technically sound. The moderators do not consider whether the NEP is likely or not to get accepted.
    • The title accurately reflects the content.
    • The language, spelling, grammar, sentence structure, and code style are correct and conformant.
  2. If the NEP is not ready for approval, the moderators will send it back to the author with specific instructions in the PR. The moderators must complete the review within one week.
  3. Once the moderators agree that the PR is ready for review, they will ask the approvers (working group members) to nominate a team of at least two reviewers (subject matter experts) to review the NEP. At least one working group member must explicitly tag the reviewers and comment: "As a working group member, I'd like to nominate @SME-username and @SME-username as the Subject Matter Experts to review this NEP." If the assigned reviewers feel that they lack the relevant expertise to fully review the NEP, they can ask the working group to re-assign the reviewers for the NEP.
  4. The reviewers must finish the technical review within one week. Technical Review Guidelines:
    • First, review the technical details of the proposals and assess their merit. If you have feedback, explicitly tag the author and comment: "As the assigned Reviewer, I request from @author-username to [ask clarifying questions, request changes, or provide suggestions that are actionable.]." It may take a couple of iterations to resolve any open comments.
    • Second, once the reviewer believes that the NEP is close to the voting stage, explicitly tag the @near/nep-moderators and comment with your technical summary. The Technical Summary must include:
      • A recommendation for the working group: "As the assigned reviewer, I do not have any feedback for the author. I recommend moving this NEP forward and for the working group to [accept or reject] it based on [provide reasoning, including a sense of importance or urgency of this NEP]." Please note that this is the reviewer's personal recommendation.
      • A summary of benefits that surfaced in previous discussions. This should include a concise list of all the benefits that others raised, not just the ones that the reviewer personally agrees with.
      • A summary of concerns or blockers, along with their current status and resolution. Again, this should reflect the collective view of all commenters, not just the reviewer's perspective.
  5. The NEP author can make revisions and request further reviews from the reviewers. However, if a proposal is in the review stage for more than two months, the moderator will automatically reject it. To reopen the proposal, the author must restart the NEP process again.
  6. Once both reviewers complete their technical summary, the moderators will notify the approvers (working group members) that the NEP is in the final comment period. The approvers must fully review the NEP within one week. Approver guidelines:
    • First, read the NEP thoroughly. If you have feedback, explicitly tag the author and comment: "As a working group member, I request from @author-username to [ask clarifying questions, request changes, or provide actionable suggestions.]."
    • Second, once the approver believes the NEP is close to the voting stage, explicitly comment with your voting indication: "As a working group member, I lean towards [approving OR rejecting] this NEP based on [provide reasoning]."
  7. Once all the approvers indicate their voting indication, the moderator will review the voting indication for a 2/3 majority:
    • If the votes lean toward rejection: The moderator will summarize the feedback and close the NEP.
    • If the votes lean toward approval: The moderator will schedule a public call (see NEP Communication) for the author to present the NEP and for the working group members to formalize the voting decision. If the working group members agree that the NEP is overall beneficial for the NEAR ecosystem and vote to approve it, then the proposal is considered accepted. After the call, the moderator will summarize the decision on the NEP.
  8. The NEP author or other assignees will complete action items from the call. For example, the author will finalize the "Changelog" section on the NEP, which summarizes the benefits and concerns for future reference.

Transferring NEP Ownership

While a NEP is worked on, it occasionally becomes necessary to transfer ownership of NEPs to a new author. In general, it is preferable to retain the original author as a co-author of the transferred NEP, but that is up to the original author. A good reason to transfer ownership is that the original author no longer has the time or interest in updating it or following through with the NEP process. A bad reason to transfer ownership is that the author does not agree with the direction of the NEP. One aim of the NEP process is to try to build consensus around a NEP, but if that is not possible, an author can submit a competing NEP.

If you are interested in assuming ownership of a NEP, you can also do this via pull request. Fork the NEP repository, modify the owner, and submit a pull request. In the PR description, tag the original author and provide a summary of the work that was previously done. Also clearly state the intent of the fork and the relationship of the new PR to the old one. For example: "Forked to address the remaining review comments in NEP # since the original author does not have time to address them.

What does a successful NEP look like?

Each NEP should be written in markdown format and follow the NEP-0000 template and include all the appropriate sections, which will make it easier for the NEP reviewers and community members to understand and provide feedback. The most successful NEPs are those that go through collective iteration, with authors who actively seek feedback and support from the community. Ultimately, a successful NEP is one that addresses a specific problem or needs within the NEAR ecosystem, is well-researched, and has the support of the community and ecosystem experts.

Auxiliary Files

Images, diagrams, and auxiliary files should be included in a subdirectory of the assets folder for that NEP as follows: assets/nep-N (where N is to be replaced with the NEP number). When linking to an image in the NEP, use relative links such as .../assets/nep-1/image.png

Style Guide

NEP numbers

When referring to a NEP by number, it should be written in the hyphenated form NEP-X where X is the NEP's assigned number.

RFC 2119

NEPs are encouraged to follow RFC 2119 for terminology and to insert the following at the beginning of the Specification section:

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

NEP Maintenance

Generally, NEPs are not modifiable after reaching their final state. However, there are occasions when updating a NEP is necessary, such as when discovering a security vulnerability or identifying misalignment with a widely-used implementation. In such cases, an author may submit a NEP extension in a pull request with the proposed changes to an existing NEP document.

A NEP extension has a higher chance of approval if it introduces clear benefits to existing implementors and does not introduce breaking changes.

If an author believes that a new extension meets the criteria for its own separate NEP, it is better to submit a new NEP than to modify an existing one. Just make sure to specify any dependencies on certain NEPs.

References

The content of this document was derived heavily from the PEP, BIP, Rust RFC, and EIP standards bootstrap documents:

Copyright

Copyright and related rights waived via CC0.