Skip to content

Latest commit

 

History

History
401 lines (294 loc) · 18.1 KB

nep-0001.md

File metadata and controls

401 lines (294 loc) · 18.1 KB
Raw
NEP Title Author DiscussionsTo Status Type Created
1
NEP Purpose and Guidelines
Jay Logelin <[email protected]>
Living
Process
03-Mar-2022

What is an NEP?

NEP stands for Near Enhancement Proposal. An NEP is a design document providing information to the Near community, or describing a new feature for the Near protocol, Smart Contract standards, or it's environment. The NEP should provide a concise technical specification of the feature and a rationale for the feature.

NEPs are intented to be the primary mechanism for proposing new features, interfacing with the community on an issue and documenting design decisions that have been integrated into Near's runtime or Smart Contract ecosystem.

As such, the NEP author is responsible for building consensus within the community and documenting dissenting opinions.

NEP Audience

The typical primary audience for NEPs are the core developers of the Near reference implementations, and Near Smart Contract developers.

However, other parts of the Near community may also choose to use the process (particularly for Informational NEPs) to document expected API conventions and to manage complex design coordination problems that require collaboration across multiple projects.

NEP Types

There are three kinds of NEP:

  1. A Standards Track NEP describes a new feature or implementation for the Near protocol or Near Smart Contract implementation standards.

  2. An Informational NEP describes a Near design issue, or provides general guidelines or information to the Near community, but does not propose a new feature. Informational NEPs do not necessarily represent a Near community consensus or recommendation, so users and implementers can ignore Informational NEPs or follow their advice.

  3. A Process NEP describes a process surrounding Near, or proposes a change to (or an event in) a process. Process NEPs are like Standards Track NEPs but apply to areas other than the Near platform itself. They may propose an implementation, but not to Near's codebase; they often require community consensus; unlike Informational NEPs, 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 Near development. Any meta-NEP is also considered a Process NEP.

NEP Workflow

Start with an idea for Near

The NEP process begins with a new idea for the Near ecosystem. It is recommended that a single NEP contain a single key proposal or new idea.

Each NEP must have a torch-bearer: someone who writes the NEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. This NEP Author should first attempt to ascertain whether the idea is NEP-able.

Vetting an idea publicly before going as far as writing an NEP is meant to save the potential author time. Many ideas have been brought forward for changing Near that have been rejected for various reasons. Asking the Near 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. 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 Near is used.

In general the process is:

  • Sign up for the governance site and make a post to the appropriate section. For instance, during the ideation phase of a standard, one might start a new conversation in the Development » Standards section. The other suggested category in the governance forum is the Development » Proposals section.

  • The forum has comment threading which allows the community and NEAR Collective to ideate, ask questions, wrestle with approaches, etc. If more immediate responses are desired, consider bringing the conversation to Discord.

Once the torch-bearer has asked the Near community as to whether an idea has any chance of acceptance, a draft NEP should be presented to the appropriate venue mentioned above. This gives the author a chance to flesh out the draft NEP to make properly formatted, of high quality, and to address initial concerns about the proposal.

Submitting an NEP

Following the above initial discussions, the workflow, the proposal should be submitted as a draft NEP via a GitHub pull request. The draft must be written in NEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors).

The standard NEP workflow is:

  • You, the NEP author, fork the NEPs repository, and create a file named neps/nep-9999.md that contains your new NEP. Use "9999" as your draft NEP number.

  • Your first update will be to change the nep filename to match the Pull Request number. For example, if the PR is 305, the NEP should be neps/nep-0305.md.

  • In the "Type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate, and for the "Status:" field enter "Draft". For full details, see NEP Header Preamble.

  • Push this to your GitHub fork and submit a pull request.

  • The NEP editors review your PR for structure, formatting, and other errors. For a markdown-formatted NEP, nep-template.md is provided as a template. Approval criteria are:

    • It is sound and complete. The ideas must make technical sense. The editors do not consider whether they seem likely to be accepted.
    • The title accurately describes the content.
    • The NEP's language (spelling, grammar, sentence structure, etc.) and code style should be correct and conformant.

    If the NEP isn't ready for approval, an editor will send it back to the author for revision, with specific instructions in the pull request.

Once the review process is complete, and the NEP editors approve it (note that this is not the same as accepting your NEP!), they will squash commit your pull request onto main.

The NEP editors will not unreasonably deny publication of an NEP. Reasons for denying NEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the NEAR philosophy.

As updates are necessary, the NEP author can check in new versions if they (or a collaborating developer) have write access to the NEP repository.

Standards Track NEPs consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation be co-developed with the NEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation.

NEP Maintenance

Informational and Process NEPs may be updated over time to reflect changes to development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the NEP being updated. In general, Standards track NEP's are no longer modified after they have reached the Final state.

NEP Process State

The following is the standardization process for all NEPs in all tracks:

NEP Status Flow Diagram

Idea - An idea that is pre-draft. This is not tracked within the NEP Repository.

Draft - The first formally tracked stage of an NEP in development. An NEP is merged by an NEP Editor into the NEP repository when properly formatted.

Review - An NEP Author marks an NEP as ready for and requesting Peer Review.

Last Call - This is the final review window for an NEP before moving to Final. An NEP editor will assign Last Call status and set a review end date (last-call-deadline), typically 14 days later.

If this period results in necessary normative changes it will revert the NEP to Review.

Final - This NEP represents the final standard. A Final NEP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications.

Living - A special status for NEPs that are designed to be continually updated and not reach a state of finality. This includes most notably NEP-0001.

What does a successful NEP look like?

Each NEP should have the following parts/sections:

  1. Preamble - RFC 822 style headers containing meta-data about the NEP, including the NEP number, a short descriptive title, the names, and optionally the contact info for each author, etc.

  2. Summary - a short (~200 word) description of the technical issue being addressed.

  3. Motivation - The motivation section should clearly explain why the existing contract ecosystem is inadequate to address the problem that the NEP solves. This can include collecting documented support for the NEP from important projects in the Near ecosystem. NEP submissions without sufficient motivation may be rejected.

  4. Rationale and alternatives - The rationale fleshes out the specification by describing why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other platforms.

  5. Specification - The technical specification should describe the syntax and semantics of the contract or protocol feature. The specification should be detailed enough to allow competing, interoperable implementations for at least the current major Near version.

  6. Reference Implementation - The reference implementation must be completed before any Standards Track in the Contract category NEP is given status "Final", but it need not be completed before the NEP is accepted. For other Categories, this section is optional.

    While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.

    The final implementation must include test code and documentation appropriate in a Near-compatible contract language.

    Appropriate judgement should be used when defining the reference implementation, which can be included inline or reference an external github repository.

    Where possible, include a Minimum Viable Interface expressing the required behavior and types in a target Near Contract language. (ie. traits and structs for rust, interfaces and classes for javascript, function signatures and structs for c, etc.) Expressions of such interfaces helps define the link between contract standardization and implementation.

  7. Security Implications - If there are security concerns in relation to the NEP, those concerns should be explicitly written out to make sure reviewers of the NEP are aware of them.

  8. Drawbacks - Throughout the discussion of an NEP, various ideas will be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This both helps record the thought process behind the final version of the NEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions.

    In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued.

  9. Unresolved Issues - While an NEP is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the NEP to be ready for consideration are complete and reduces people duplicating prior discussion.

  10. Future possibilities - Future possibilities describes any natural extensions and evolutions to the NEP proposal and how it would affect the project. Try to use this section as a tool to more fully consider all possible interactions with the project in your proposal. Also consider how the this all fits into the roadmap for the project and of the relevant sub-teams.

  11. Copyright Waiver - All NEPs must be in the public domain. See the bottom of this NEP for an example copyright waiver.

NEP Header Preamble

Each NEP must begin with an RFC 822 style header preamble. The headers must appear in the following order.

  NEP: <NEP number>
  Title: <NEP title>
  Author: <list of authors' real names and optionally, email addrs>
  DiscussionsTo: <URL of current canonical discussion thread or threads>
  Status: <Draft | Review | Last Call | Final | Living | Deprecated>
  Type: <Standards Track | Informational | Process>
  Category: if Type is "Standards Track" one of <Protocol | Contract | Runtime>
  Requires (Optional): <NEP numbers>  
  Replaces (Optional): <NEP number>
  SupersededBy (Optional): <NEP number>
  Created: <date created on, in dd-mmm-yyyy format>

Title: The NEP title header should not be more than 4-5 words, describing

Author: The Author header lists the names, and optionally the email addresses of all the authors/owners of the NEP. The format of the Author header value must be

Random J. User <[email protected]>

if the email address is included, and just

Random J. User

If there are multiple authors, each should be on a separate line following RFC 822 continuation line conventions.

DiscussionsTo: The DiscussionsTo header provides the URL to the current canonical discussion thread for the NEP.

Type: The Type header specifies the type of NEP: Standards Track, Informational, or Process.

Category: The Category header only exists iff the Type header is Standards Track, one of Protocol, Contract or Runtime.

Created: The Created header records the date that the NEP was assigned a number, should be in dd-mmm-yyyy format, e.g. 03-Mar-2022.

Requires: NEPs may have a Requires header, indicating the NEP numbers that this NEP depends on.

SupersededBy: NEPs may also have a SupersededBy header indicating that an NEP has been rendered obsolete by a later document; the value is the number of the NEP that replaces the current document.

Replaces: A newer NEP marked with a SupercededBy header must have a Replaces header containing the number of the NEP that it rendered obsolete.

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

Transferring NEP Ownership

It occasionally becomes necessary to transfer ownership of NEPs to a new torch-bearer. In general, it is preferable to retain the original author as a co-author of the transferred NEP, but that's really up to the original author. A good reason to transfer ownership is because 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 because the author doesn't agree with the direction of the NEP. One aim of the NEP process is to try to build consensus around an NEP, but if that's not possible, an author can submit a competing NEP.

If you are interested in assuming ownership of an NEP, you can also do this via pull request. Fork the NEP repository, make your ownership modification, and submit a pull request. You should mention both the original author and @near/nep-editors in a comment on the pull request.

NEP Editors

The current NEP Editors are:

  • Jay Logelin - @jlogelin

NEP Editor Responsibilities & Workflow

Note that developers with write access to the NEP repository may handle the tasks that would normally be taken care of by the NEP editors.

For each new NEP that comes in, an editor does the following:

  • Read the NEP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to get to final status.
  • The title should accurately describe the content.
  • Check the NEP for language (spelling, grammar, sentence structure, etc.), markup (GitHub flavored Markdown), code style

Several NEPs are written and maintained by developers with write access to the Near codebase. The NEP editors monitor the NEP repository for changes, and correct any structure, grammar, spelling, or markup mistakes they see.

NEP editors don't pass philosophical judgment on NEPs. They merely do the administrative & editorial part.

Style Guide

NEP numbers

When referring to an 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 key words “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.

References

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

Copyright

Copyright and related rights waived via CC0.