Iron out NEP process that starts with governance site discussion (#234)

* Adding an NEP for NEAR Shell enhancements (#30)

* flesh out translation, location of key and config storage, massage commands

* add upgradability, project-level settings notion

* cleanup, add prompt details, fix priority wording, move network to future

* rework location of connection configuration, clarity across the board

* more user stories, mention future ideas, remove validator references

* add info about home directory settings, esp regarding metrics, settings commands

* clarify some settings are home-only & project-only

* differentiate shell-experience & project-level settings

* minor corrections, introductory paragraph, remove incorrect metrics info

* add "network" key to key file

* by default key files are stored in the home directory

* distinguish validators and proposals command

* pass at modifying the README

* add mdBook info to readme

* initial summary and section for proposals

* mv near-shell md file to Proposals section

* rename 31-near… to 0031-near…

* correct top section, reduce confusion replacing "near shell" with NEAR CLI

* remove the near shell entry

* move archived proposals into the Proposals

* update the mdbook SUMMARY.md to include the new (old archived) proposals

* flesh out README landing page for Proposals

* rework wording on top-level README

* include suggestion to use the gov site proposals category

* Update README.md

Co-authored-by: Damon Sicore <[email protected]>
Co-authored-by: Bowen Wang <[email protected]>

README.md

@@ -1,37 +1,61 @@
 # NEAR Protocol Specifications and Standards
 
 This repository hosts the current NEAR Protocol specification and standards.
-Including core protocol specification, APIs, contract standards, processes and workflows.
+This includes the core protocol specification, APIs, contract standards, processes, and workflows.
 
-Both changes to the core specification and standards are called Near Enhancement Proposals (NEPs).
+Changes to the protocol specification and standards are called NEAR Enhancement Proposals (NEPs).
+
+This repository uses [mdBook](https://rust-lang.github.io/mdBook) for the [Nomicon website](https://nomicon.io).
 
 ## Specification
 
-NEAR Specification is under active development. Latest version can be found - https://nomicon.io
-Specification defines how any NEAR client should be connecting, producing blocks, reaching consensus, processing state transitions and runtime APIs.
+NEAR Specification is under active development.
+Specification defines how any NEAR client should be connecting, producing blocks, reaching consensus, processing state transitions, using runtime APIs, and implementing smart contract standards as well.
+
+## Standards & Processes
+
+Standards refer to various common interfaces and APIs that are used by smart contract developers on top of the NEAR Protocol.
+For example, such standards include SDK for Rust, API for fungible tokens or how to manage user's social graph.
+
+Processes include release process for spec, clients or how standards are updated.
 
 ### Contributing
 
-Spec changes are done via PRs to this repository.
+#### Expectations
+
+Ideas presented ultimately as NEPs will need to be driven by the author through the process. It's an exciting opportunity with a fair amount of responsibility from the contributor(s). Please put care into the details. NEPs that do not present convincing motivation, demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly received. Again, by the time the NEP makes it to the pull request, it has a clear plan and path forward based on the discussions in the governance forum.
+
+#### Process
+
+Spec changes are ultimately done via pull requests to this repository. However, in an effort to keep the pull request clean and readable, please follow these instructions to flesh out an idea.
+
+1. 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).
+2. 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).
+3. When the governance conversations have reached a point where a clear plan is evident, create a pull request, using the instructions below.
+
+Pull request (only when governance discussion has concluded)
 
 * Clone this repository and create a branch with "my-feature".
-* Update relevant places in the specification with proposal.
-* Create PR, where information of the PR follows 0000-template.md to describe motivation and details of the change to the protocol.
-* Receive feedback from the community and revise as suggested.
+* Update relevant content in the current specification that are affected by the proposal.
+* Create PR, where information of the PR follows [0000-template.md](0000-template.md) to describe motivation and details of the change to the protocol. The file will be added to `specs/Proposals`, using the pull request number padded with zeroes. For instance, the pull request `19` might be created as `specs/Proposals/0019-short-slug-description.md`.
 * Post pre-approval of the spec change, present a PR for NEAR Protocol client(s) that implements this specification change.
-* Receive final approval and merge change into the `master` to be included in the next specification release.
+* Receive final approval and merge change into the `master` to be included in the next release.
 
-## Standards & Processes
+Tip: build consensus and integrate feedback. NEPs that have broad support are much more likely to make progress than those that don't receive any comments. Feel free to reach out to the NEP assignee in particular to get help identify stakeholders and obstacles.
 
-Standards refer to various common interfaces and APIs that are used by smart contract developers on top of the NEAR Protocol.
-For example, such standards include SDK for Rust, API for fungible tokens or how to manage user's social graph.
+### Running mdBook
 
-Processes include release process for spec, clients or how standards are updated.
+For Linux and OS X, you may run:
 
-### Contributing
+`./build.sh`
+
+For Windows:
+
+```bash
+cargo install mdbook
+mdbook build
+```
+
+To quickly iterate, you may also use the command:
 
-* Copy `0000-template.md` to `text/0000-my-feature.md` (where "my-feature" is descriptive. don't assign an NEP number yet).
-* If applicable, link to the issued in specific repositories;
-* Fill in the NEP. Put care into the details: NEPs that do not present convincing motivation, demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or alternatives tend to be poorly received.
-* Submit a pull request. As a pull request the NEP will receive design feedback from the larger community, and the author should be prepared to revise it in response.
-* Build consensus and integrate feedback. NEPs that have broad support are much more likely to make progress than those that don't receive any comments. Feel free to reach out to the NEP assignee in particular to get help identifying stakeholders and obstacles.
+`mdbook serve`

specs/Proposals/README.md

@@ -0,0 +1,14 @@
+## Proposals
+
+This section contains the NEAR Enhancement Proposals (NEPs) that cover a fleshed out concept for NEAR. Before an idea is turned into a proposal, it will be fleshed out and discussed on the [NEAR Governance Forum](https://gov.near.org).
+
+These subcategories are great places to start such a discussion:
+
+- [Standards](https://gov.near.org/c/dev/standards/29) — examples might include new protocol standards, token standards, etc.
+- [Proposals](https://gov.near.org/c/dev/proposals/68) — ecosystem proposals that may touch tooling, node experience, wallet usage, and so on.
+
+Once and idea has been thoroughly discussed and vetted, a pull request should be made according to the instructions at the [NEP repository](https://github.com/near/NEPs).
+
+The proposals shown in this section have been merged and exist to offer as much information as possible including historical motivations, drawbacks, approaches, future concerns, etc.
+
+Once a proposal has been fully implemented it can be added as a specification, but will remain a proposal until that time.

specs/SUMMARY.md

@@ -60,3 +60,11 @@
       - [Enumeration](Standards/NonFungibleToken/Enumeration.md)
       - [Royalty Payout](Standards/NonFungibleToken/Payout.md)
   - [Storage Management](Standards/StorageManagement.md)
+- [Proposals](Proposals/README.md)
+  - [Access Keys](Proposals/0005-access-keys.md)
+  - [Wasm bindings](Proposals/0006-bindings.md)
+  - [Batch transactions](Proposals/0008-transaction-refactoring.md)
+  - [System Methods](Proposals/0013-system-methods.md)
+  - [Execution Outcome](Proposals/0017-execution-outcome.md)
+  - [View/Change Methods](Proposals/0018-view-change-method.md)
+  - [Economics](Proposals/0033-economics.md)