Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

updated nep-0001 #350

Closed
wants to merge 2 commits into from
+82 −58
Closed

updated nep-0001 #350

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
208a82f
updated nep-0001 with roles and ownership section; proposal process r…
10d9e Apr 8, 2022
07c2baa
updated standards flow diagram
10d9e Apr 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Changes to the protocol specification and standards are called NEAR Enhancement

|NEP # | Title | Author | Status |
|---|---|---|---|
|[0001](https://github.com/near/NEPs/blob/master/neps/nep-0001.md) | NEP Purpose and Guidelines | @jlogelin | Living |
|[0001](https://github.com/near/NEPs/blob/master/neps/nep-0001.md) | NEP Purpose and Guidelines | @nearmax @matklad @jlogelin | Living |
|[0021](https://github.com/near/NEPs/blob/master/neps/nep-0021.md) | Fungible Token Standard (Deprecated) | @evgenykuzyakov | Final |
|[0141](https://github.com/near/NEPs/blob/master/neps/nep-0141.md) | Fungible Token Standard | @evgenykuzyakov @oysterpack | Final |
|[0145](https://github.com/near/NEPs/blob/master/neps/nep-0145.md) | Storage Management | @evgenykuzyakov | Final |
Expand Down
Binary file modified neps/assets/nep-0001/NEP-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed neps/assets/nep-0001/NEP-states.png
View file
Open in desktop
Binary file not shown.
138 changes: 81 additions & 57 deletions neps/nep-0001.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
NEP: 1
Title: NEP Purpose and Guidelines
Author: Jay Logelin <[email protected]>
DiscussionsTo: https://github.com/near/NEPs/pull/333
Author: Jay Logelin <[email protected]>, Maksym Zavershynskyi <[email protected]>, Aleksey Kladov
<[email protected]>
DiscussionsTo: https://github.com/near/NEPs/pull/333, https://gov.near.org/t/quality-control-for-protocol-api-changes/1941
Status: Living
Type: Process
Created: 03-Mar-2022
Expand Down Expand Up @@ -57,49 +58,48 @@ There are three kinds of NEP:
changes to the tools or environment used in Near development.
Any meta-NEP is also considered a Process NEP.

## NEP Workflow
## The Proposal Process
One of the primary goals of the NEP process is to prevent proposals being stuck in a limbo state of always being in progress, therefore NEP participants shall commit to always either accept or reject a `Draft` proposal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to play devil's advocate here: I think "stuck in limbo" is a fairly common outcome for many of Rust's RFCs (eg, two of the three RFCs I authored can be described as stuck). This if course is suboptimal, but it seems that the final Result (the Rust language) is doing fine. Stuckness also is a useful signal -- it shows the lack of motivation, implementation capacity, or certainty.

So I'd say that the process's "primary goal" is to facilitate reliable and proactive protocol evolution, and fast accepting/rejecting is just "one of the goals"


### Start with an idea for Near
It can be rejected for the following reasons:

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.
* No-op proposal. It does not improve any of our values or velocity

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.
* Unjustifiable trade-offs. It makes the trade-offs in technological values or velocity that are not justifiable. Note, that if proposal is too difficult to implement or it adds too much architectural complexity it can be rejected as impeding future velocity too much.

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.
* Not ready. The proposal does not satisfy the required format, e.g. it does not explain all standard scenarios. Also, we don’t want the proposal discussion the be the place where the process is created, and so the authors and the proponents should come with a sufficiently ready proposal and do not expect to iterate on it with the community. They can however iterate on the proposal with the community in other open forums outside the official proposal process. Therefore, if proposal is submitted but community keeps finding gaps in the proposal, e.g. like reasonable alternatives, adversarial angles or gaps in the design, then even if author and proponents continue explaining them, after some time proposal runs out of time and is rejected.

In general the process is:
* Duplicate. A similar proposal has been already submitted and the author did not explain the difference sufficiently.

* Sign up for the [governance site](https://gov.near.org/) 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](https://gov.near.org/c/dev/standards/29).
The other suggested category in the governance forum is the
[Development » Proposals section](https://gov.near.org/c/dev/proposals/68).
* Spam. Someone is trying to get their proposal through by spamming;
The time-line of the proposal is the following:

* 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](https://near.chat).
### Initial phase (1 week at most)

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.
1.1. The process is initiated by an author submitting it in `Draft` status.

1.2. The proposal is examined by the admins. If it deviates from the format the proposal's status is set to `Rejected` and allowed to be resubmitted in 1 month.

1.3. Admins invite SMEs (some SMEs recognized by admins might join voluntarily) and representatives from the affected projects.

1.4. (Optional) The stakeholders hire the auditors.

1.5. Admins update the status to `Review` to indicate readiness for the next phase.

### Discussion phase (2 months at most)

2.1. SMEs and affected projects weigh-in.

2.2. Auditors respond with their findings.

2.3. Other community members join the discussion.

2.4. Once the proposal is at the point where it is exhaustive, non-ambiguous, highly-detailed, and all findings are addressed and incorporated into the proposal, the admins make a decision on accepting or rejecting it.

2.5. If proposal runs out of time it is rejected.

### Implementation phase
3.1. Admins invite representatives from the affected projects and the implementers to discuss the timeline of rolling out the feature. Once the timeline is agreed on, the remaining process is delegated to the implementers.

## Submitting an NEP

Expand Down Expand Up @@ -136,7 +136,7 @@ The standard NEP workflow is:
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
Once the review process is complete, and the NEP editors approve or reject it (note that
this is *not* the same as accepting your NEP!), they will squash commit your
pull request onto main.

Expand All @@ -161,15 +161,15 @@ 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
## NEP Process States

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

![NEP Status Flow Diagram](assets/nep-0001/NEP-flow.png)

**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.
**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 and vetted, see `Initial Phase` in the previous section.

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

Expand Down Expand Up @@ -346,31 +346,55 @@ 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
## Roles, Ownership, and Accountability
The overall NEP process should balance democracy and inclusivity, with accountability. This means the proposal needs to have owners – people who carry the burden of proving “beyond reasonable doubt” that the proposed design does what it claims to do and that it does not negatively affect our technological values or impede future velocity. The owners of the proposal are the author and its potential proponents. It is their responsibility to prove that the proposal works, and it is not responsibility of others to prove that it does not work. The default decision for any protocol change should be a No.

There are defined administators who will decide when the proposal is accepted or rejected. In the long run, this will be a council elected by the stakeholders, which most likely will be only the validators and people that validators consider as an authority or experts, since validators have an ultimate control of deciding which protocol version to run on their machines. In the short term, process admins will be a preselected group of people. Admins will also be moderating the discussion once the proposal is submitted to make sure the discussion is civil and focused.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Admins will also be moderating the discussion once the proposal is submitted to make sure the discussion is civil and focused

If we have extra people power, it would be much better to have a dedicated moderation team. Admins themselves should be moderated, and that shouldn't involve conflict of interests.

To bootstrap the process, I think it's OK to lump the two responsibilities together.

But maybe we can say something like "there's admin team, who does this" and "there's mod team, who does that", and than, separately "to bootstrap the process, both teams would intersect".


As explained above, there will be opponents and people nominated to play the opposing force and try to do the following:

* Find gaps, double-interpretations, inconsistencies
* Suggest better alternatives and ask author and proponents to justify why alternative is not better
* Find angles of attack and other kinds of abuse
* If the proposed design makes trade-offs with our technological values and velocity, then argue why these trade-offs are not justifiable
* Additionally, there are people who work on different parts of the protocol and have deep understanding of it. It makes sense to invite them into the discussion and when judgement call is needed (e.g. when the trade-offs are present) ask them to weigh-in.

To summarize, the roles are:

### Author
Election process: Self-elected by submitting a proposal.

Responsibilities: Submit the proposal following the format, address the comments from the community until proposal is accepted.

### Administrator (Editor)
Election process: Initially pre-selected, but eventually elected by the validators. They are the same for all proposals.

Responsibilities: Moderate the discussion, make the final accept/reject decision, enforce the timeline, recognize/invite subject matter experts.

### Incentivized Auditors
Election process: Funded by stakeholders, e.g. NEAR Foundation;
Responsibilities: scrutinize the proposal, the incentive model might be paying per finding.

### Subject Matter Experts (SMEs)
Election process: recognized or nominated by admins either for all proposals or for specific proposals.

The current NEP Editors are:
* Jay Logelin - @jlogelin
Responsibilities: Present their take on the specific proposal.

## NEP Editor Responsibilities & Workflow
### Affected projects
Election process: The author of the proposal needs to list all major projects that will be affected by the change in the proposal. Admins then invite representatives from major projects for the discussion.

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.
Responsibilities: Explain in detail how they will be affected if the proposal is implemented.

For each new NEP that comes in, an editor does the following:
### Community Members
Election process: none, anyone can join the discussion as proponent, opponent, or non-incentivized auditor.

* 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
Responsibilities: Add clarity to the discussion, surface issues, present alternative points of view.

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.
### Implementers
Election process: self-elected by being one of the owners of a client implementation for our protocol.

NEP editors don't pass philosophical judgment on NEPs. They merely do the
administrative & editorial part.
Responsibilities: implement the change, if accepted. Very likely, they will be in sync with the validators and other stakeholders so they will have an interest in implementing the change;
Note, some roles might overlap, e.g. the implementers will also likely be the SMEs. However, certain roles should be separate to avoid conflicts of interest, e.g. the author should be separate from the admins and the auditors. If the admins want to submit a proposal themselves then they need to recuse themselves from the process.

## Style Guide

Expand Down