NIP-1_NIP Purpose and Guidelines

NIP: 1
Title: NIP Purpose and Guidelines
Status: Last call
Type: Process
Author: Lin Yang <lin@nuls.io>
Created: 2018-12-27

What is a NIP?

NIP stands for NULS Improvement Proposal. A NIP is a design document providing information to the NULS community, and can be used for describing a new feature for NULS or its processes or environment. The NIP author is responsible for building consensus within the community and documenting dissenting opinions.

Reasons for NIP

  • We intend NIPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into NULS. Because the NIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
  • For NULS implementers, NIP is a convenient means to track their progress. Ideally, the maintainers of each feature will list the NIPs they have implemented. This provides a convenient way for users to understand the current status of a feature or library.

NIP Types

There are six types of NIP:

  • A Core NIP describes improvements in the NULS core code, such as consensus mechanisms, network protocols, etc.
  • A Module NIP describes improvements in module submission and review requirements, such as the certain minimum criteria a NIP must meet to be accepted and merged into the module repository.
  • An Interface NIP describes improvements in the specifications and standards of the NULS client API/RPC, such as API name and method name.
  • An NRC Standards NIP describes improvements in application-level standards, such as contract standards, token standards, etc.
  • An Informational NIP describes a NULS design issue or provides general guidelines or information to the NULS community–but does not propose a new feature. Informational NIPs do not necessarily represent a NULS community consensus or recommendation, so users and implementers are free to ignore Informational NIPs or follow their advice.
  • A Process NIP describes improvements in all NULS-related operational processes, such as the ambassador election in the community. A Process NIP is not only a recommendation, but also a specification that community members need to follow to accomplish certain things, but it does not involve code-level specifications.

NIP Work Flow

The parties involved in the workflow include some or all of the following roles:

  • Most members of the community

    The main responsibility is to participate in the discussion and voting of the NIPs, making constructive comments as well.

  • NIP Authors

    Propose and improve NIPs and lead the community to discuss.

  • NIP Editors

    Manage and edit NIPs.

  • NULS Council

    The NIPs, about to “Final” or “Accepted”, can be rejected by the final decision of the Council via internal voting.

  • NULS Core Developers

    They are responsible for the audit and code implementation of the Core, Module, NRC Standards and Interface NIPs.

Vetting an idea publicly before going as far as writing a NIP is meant to save your time. Asking the 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 NULS is used. We recommend that comments can be collected in the community via voting, and the results will also help the NIP editors to make quicker decisions on whether to merge the NIP.

A successful NIP requires the following stages:

  [ Draft ]->[ Last Call ]->[ Accepted ]->[ Final ]

Each change to the NIP status should be submitted by the NIP author as a pull request (PR), and the NIP editors will review the NIP. It’s a good idea to add a link to the discussion post when you submit a PR.

A complete NIP process is as follows:

  • The NIP author writes the NIP using the mandated format and style and shepherds the discussions in the community. The NIP author should first attempt to ascertain whether the idea is NIP-able, and then submit the NIP as a PR to the NIP repository, including a link to the discussion post. The NIP editors will handle these requests based on actual situation.

    • Draft: Once approved, the NIP editors will assign the NIP a number and squash commit the pull request onto master. The NIP editors will not unreasonably deny a NIP.
    • Draft: Reasons for denying NIP status include being unfocused or too broad, duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the NULS philosophy.
  • Updates to drafts may also be submitted by the author as pull requests before it can be considered mature enough and ready for the next status.

    • Last call: Once approved, the NIP editors will change the NIP status from Draft to last call and set the end date for the last call, usually 15 days.
    • Last call: Once the NIP has been published, it will be re-assigned to Draft status when necessary revisions are made on the NIP. We hope that a NIP will enter last call status only once to avoid unnecessary controversy in the community.
  • The NIP in last call status will be pinned at https://forum.nuls.io/

    • Accepted (involved in Core, Module, NRC Standards and Interface NIPs only): If there are no major revisions or open technical issues, the status of the NIP through the last call period will be changed to “Accepted” by the NIP editors.
    • Final (involved in Informational and Process NIPs only): If there are no major revisions or open technical issues, the status of the NIP through the last call period will be changed to “Final” by the NIP editors.
    • Last call: The NIP will be re-assigned to Draft status if there are material changes or technical issues raised by the community cannot be solved during the last call period. In addition, if the Council has different views on the NIP, a vote can be initiated within the Council members. If more than 70% of the Council members reject the NIP (giving reasons), the NIP will be re-assigned to “Draft” status or directly “Rejected” according to actual reasons.
  • Once the Core, Module, NRC Standards and Interface NIPs have been accepted, the NULS core developers must implement the NIPs in the form of code before they can be considered “Final”.

    • Final (involved in Core, Module, NRC Standards and Interface NIPs only): After the NIP is implemented in the form of code, and is running on the main-net stably for certain amount of time or has become effectively verified, with changes recognized by the community as well, the status can be changed to “Final”.

Other exceptional statuses are:

  • Deferred: Once the Core, Module, NRC Standards and Interface NIPs have been accepted, the developers do not complete the reference implementation as scheduled.
  • Rejected: A NIP can also be “Rejected”. Perhaps core developers reject to propose an implementation or the Council finds it unfeasible.
  • Superseded: A NIP used to “Final”, but it is no longer considered the most advanced. Another better NIP appears, referring to this NIP, and becomes the Final status.

What belongs in a successful NIP?

Each NIP should have the following parts: (those marked with “*” are optional):

  • **Preamble:**RFC 822 style headers containing meta-data about the NIP, including the NIP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc. See NIP Header Preamble for details.
  • Summary: The NIP author needs to provide a simple and understandable summary of the NIP for the general public. If you can’t explain it in a simple way, it means that you don’t fully understand it.
  • Abstract: A short (~200 word) description of the technical issue being addressed.
  • Motivation: The motivation is critical for NIPs that want to change the NULS protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the NIP solves. NIP submissions without sufficient motivation may be rejected outright.
  • Specification: The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current NULS platforms (NULS client, explorer).
  • Rationale: The rationale fleshes out the specification by describing what motivated the design and 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 languages. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
  • Backwards Compatibility: All NIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The NIP must explain how the author proposes to deal with these incompatibilities. NIP submissions without a sufficient backwards compatibility treatise may be rejected outright.
  • Test Cases: For NIPs that affect the consensus mechanism, test cases for their implementation must be provided.
  • **Reference Implementation:**The reference implementation must be completed before any NIP is given status “Final”, but it need not be completed before the NIP is accepted.
  • **History:**History records show the whole process of the NIP from being proposed to the Final state, which can be displayed as additional links.

NIP Formats and Templates

NIP should be written in markdown format.

NIP Header Preamble

Each NIP must use the RFC 822 style as the head of the document. The headers must be arranged in the following order. The headers marked with * are optional, others are required.

  Title: < NIP title>
  Author: <list of authors' real names and optionally, email addrs>
* Discussions-To: < links to official discussion channels>
  Status: <Draft | Accepted | Final | Superseded | Deferred | Rejected>
  Type: <Core | Module | Interface | NRC Standards | Informational | Process>
  Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
* Replaces: < NIP number>
* Superseded-By: < NIP number>

Auxiliary Files

NIPs may include auxiliary files such as diagrams. Auxiliary files must be named NIP-XXXX-Y.ext, where “XXXX” is the NIP number, “Y” is a serial number (starting at 1), and “ext” is replaced by the actual file extension (e.g. “png”).

Transferring NIP Ownership

It occasionally becomes necessary to transfer ownership of NIPs to a new champion. In general, we’d like to retain the original author as a co-author of the transferred NIP, 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 NIP process or has fallen off the face of the ‘net’ (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because you don’t agree with the direction of the NIP. We try to build consensus around a NIP, but if that’s not possible, you can always submit a competing NIP.

If you are interested in assuming ownership of a NIP, send a message asking to take over, addressed to both the original author and the NIP editors. If the original author doesn’t respond to email in a timely manner, the NIP editors will make a unilateral decision (it’s not like such decisions can’t be reversed).

NIP Editors

The current NIP editors are:

Niels <Niels@nuls.io>
Pen <Pen@nuls.io>

NIP Editor Responsibilities

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

  • Read the NIP to check if it is ready: sound and complete. The ideas in the NIP must make technical sense, even if they don’t seem likely to be accepted.
  • The title should accurately describe the content.
  • Skim the NIP for obvious defects in language (spelling, grammar, sentence structure, etc.), markup (for Github style), and code style.

If the NIP isn’t ready, an editor will send it back to the author for revision, with specific instructions. Once the NIP is ready for the repository, a NIP editor will:

  • Assign a NIP number (usually a PR number)
  • Merge the pull request
  • Send email back to the NIP author with next steps

Many NIPs are written and maintained by developers with write access to the NULS codebase. The NIP editors monitor NIP changes, and correct any structure, grammar, spelling, or markup mistakes they see. NIP editors don’t pass judgment on NIPs. They merely do the administrative and editorial part.

History

This document was derived heavily from Bitcoin’s Bitcoin’s BIP-0001, written by Amir Taake, and the text he wrote was mainly from Python’s PEP-0001. According to this situation, NIP makes some modifications based on their documents, such as adding the Council in the NIP process, modifying NIP types, etc. Please direct all comments to the NULS NIP editors.

NIP:1
标题: NIP的目的和指导
状态: 公示
类型: 流程
作者: Lin Yang <lin@nuls.io>
创建日期:2018/12/27

什么是NIP?

NIP代表NULS改善提案。 NIP是一个设计文档,用于向NULS社区提供信息,描述NULS相关的改善流程或新功能。 NIP作者负责在社区内建立共识并记录不同意见。

NIP产生的理由

  • 我们希望NIP成为提出新功能、收集社区技术意见以及记录NULS设计决策的主要机制。 由于NIP在版本化存储库中被作为文本文件维护,因此其修订历史记录就是功能提议的历史记录

  • 对于NULS实施者,NIP是跟踪其实施进度的便捷手段。 理想情况下,每个功能的维护者都会列出他们已实现的NIP。 这将为用户提供一种方便的方法来了解某个功能或库的当前状态。

NIP的类型

NIP当前有六种类型:

  • 核心:NULS核心代码的改善,例如共识机制,网络协议等。
  • 模块:模块的提交和评审要求的改善,例如符合何种标准的模块会被接受并被纳入模块仓库。
  • 接口:NULS客户端API/RPC的规范和标准的改善,例如API名称、方法名称。
  • NRC标准:应用级别的标准的改善,例如合约标准,通证标准等。
  • 信息:描述NULS设计问题,或向NULS社区提供一般性指导或信息,但不提出新功能。 信息NIP不一定代表NULS社区的共识或推荐,因此用户和实施者可以自由选择忽略信息NIP或遵循他们的建议
  • 流程:所有NULS相关的操作流程的改善,例如社区中竞选大使的流程的改善。流程类NIP不仅仅是建议,是社区成员完成某些特定的事需要遵守的规范,但该类NIP不涉及代码层面的规范。

NIP的工作流程

涉及流程的各方包括以下部分或全部角色:

  • 社区的大部分成员

    主要职责为参与NIP的讨论和投票,提出建设性意见。

  • NIP作者

    提出和完善NIP,并负责引导社区展开讨论。

  • NIP编辑

    管理和编辑NIP。

  • NULS理事会

    对即将进入接受或完结状态的NIP做最后把关,理事会有权通过内部投票拒绝NIP。

  • NULS核心开发者

    负责核心,模块,NRC标准和接口这四个类型的NIP的审核和代码实现。

在开始撰写NIP之前,先审查你的想法,这将帮你节省时间。首先询问社区这个想法之前是否被提出过,可行性如何。以免浪费时间在一些肯定会被拒绝的提案上,并有助于确保该想法适用于整个社区而不仅仅是作者。 某个想法对作者有意义并不意味着它对各个地区使用NULS的人都有意义。我们建议可以通过发起投票的方式在社区收集意见,投票的结果也有助于NIP编辑更快做出判断是否合并该NIP。

完成一个最终生效的NIP需要经过以下阶段:

  [ 草稿 ]->[ 公示 ]->[ 接受 ]->[ 完结 ]

每次NIP状态的更改都是先由NIP的作者提出Pull Request(合并请求,简称PR),然后NIP的编辑会对该NIP进行审查。提出PR的时候最好包含一个可以持续讨论该NIP的链接。

完整的NIP处理流程如下:

  • NIP的作者按照规定的格式和样式编写NIP,然后在社区中进行讨论和调研,确定可行性后,则将NIP通过提PR的方式提交到NIP仓库,并在PR中包含社区讨论的链接。NIP编辑会根据实际情况来处理这些请求。

    • 草稿: 如果同意合并,NIP编辑将为该NIP分配一个编号并合并PR。 NIP编辑不会无理由拒绝某个NIP
    • 草稿: 拒绝合并为草稿的原因包括专注度不够、过于宽泛、重复劳动、技术上不健全、没有提供合理的动机或解决向后兼容性,或者不符合NULS理念。
  • 合并成为草稿状态后,作者可以继续提PR对草稿做进一步更改,直至认为该NIP已经足够成熟并准备好进入下一个状态为止。

    • 公示: 如果获得同意,NIP编辑将会把该NIP的状态从草稿更改为公示,并设置公示结束日期,通常为15天后。
    • 公示: 如果进入公示阶段后,还要对该NIP进行更改,那这个NIP会被退回草稿状态。我们希望一个NIP只进入一次公示状态,避免在社区引起不必要的争论。
  • 公示状态的NIP会置顶在https://forum.nuls.io/

    • 接受(核心,模块,NRC标准和接口的NIP才涉及): 如果没有重大变更或未解决的技术问题,则通过公示期的NIP的状态会被NIP编辑更改为接受。
    • 完结(信息和流程才涉及): 如果没有重大变更或未解决的技术问题,则通过公示期的NIP的状态会被NIP编辑更改为完结。
    • 公示: 公示期有材料变更或无法解决社区提出的技术问题,则该NIP将会被退回草稿状态。除此之外,如果理事会对该NIP有不同的看法,可以在理事会成员内部发起投票,超过70%的理事会成员否决该NIP(需给出原因)则该NIP将根据实际原因被退回草稿状态或直接改为拒绝状态。
  • 当核心、模块、NRC标准和接口的NIP成为接受状态后,何时能成为完结状态取决于相关的NULS核心开发者,由他们决定如何将该NIP通过编码来实现。

    • 完结(核心,模块,NRC标准和接口的NIP涉及): NIP已通过编码实现,并在主网稳定运行一段时间或得到了有效验证且改动也得到了社区的认可,则状态可变为完结。

其他非常规的状态如下:

  • **延期:**核心、模块、NRC标准和接口相关的NIP成为接受状态后,开发者未按照预定的时间完成开发。
  • 拒绝: 某个NIP被核心开发者拒绝实现或被理事会认定为不可实现。
  • **被取代:**NIP以前是完结状态,但不再被认为是最先进的。出现另一个更好的NIP,参考了这个NIP并成为了最终状态。

一个有效的NIP文档应该包含哪些内容?

每个NIP应该包含以下部分(被*标注的代表是可选项):

  • **前言:**与NIP相关的元数据,以RFC 822样式展示。内容包括NIP编号,简短描述性标题(限制为最多44个字符)和作者详细信息。可参阅下文了解详情。
  • **简单总结:**NIP作者需要给这个NIP提供一个简单且普通人可以理解的总结,如果你不能很简单地解释它,说明你自己对它的理解还不够深入。
  • **摘要 :**对正在解决的技术问题进行简短(约200字)描述。
  • **动机:**对于想要改善NULS协议的NIP,动机至关重要。 它应该清楚地解释为什么现有的协议规范存在不足。没有足够动机的NIP可能会被彻底拒绝。
  • **规范:**技术规范应描述清楚任何新功能的语法和语义。规范应该足够详细,以允许当前任何基于NULS平台的应用拥有竞争性、可互操作性(例如NULS客户端,浏览器)。
  • **论据 :**论据通过描述什么驱动了这样的设计以及为什么要做出这样的设计决策来充实规范。它应该阐述考虑过的替代性设计和相关工作,例如如何在其他语言中支持该特性。论据也可以提供证据证明社区的意见是一致的,并应讨论提出的重要反对意见或大家关注的事项。
  • **向后兼容性:**所有引入向后不兼容的NIP必须描述存在哪些不兼容及其严重性。NIP中必须解释作者如何处理这些不兼容性。如果没有足够的向后兼容性论述,提交的NIP可能会被直接拒绝。
  • **测试用例:**对于影响共识机制的NIP,其实现方法的测试用例是强制性的。
  • **实现 :**代码的实现必须在任何NIP被赋予完结状态之前完成,但是它不需要在NIP被合并为草稿之前完成。
  • **历史记录:**历史记录是展示了该NIP从提出到成为完结状态的整个过程,可以通过附加链接形式展示。

NIP的格式和模版

NIP应该用markdown的格式编写

NIP的前言

每个NIP的必须以RFC 822的样式作为文档的头部前言,头部必须按照以下顺序进行排列,用*标注的头部为可选项,其他项为必填项

 NIP: <NIP编号>
 标题: <NIP标题>
 作者: <列出作者的真实名字和电子邮件地址>
*讨论渠道: <指向官方讨论渠道的链接>
 状态: <草稿| 接受 | 完结 | 被取代 | 延期 | 拒绝>
 类型: <核心 | 模块 | 接口 | NRC标准 | 信息 | 流程>
 创建日期: < 用 ISO 8601 (yyyy-mm-dd) 格式>
*取代: <NIP 编号>
*被取代: <NIP 编号>

附件

NIPS文档可能包含一些附件,例如流程图。这样的文件必须以NIP-XXXX-Y.ext的格式来命名,“XXXX”指的是NIP的编号,“Y”指的是序列号(从1开始),“ext”指的是文件扩展名(例如:.png)

转移NIP的所有权

有时需要将NIPS的所有权转让给新的作者。一般来说,我们希望保留原作者作为要转移的NIP的合著者,但这实际上取决于原作者。转让所有权的一个很好的理由是,原作者不再有时间或兴趣来更新它或跟进NIP的后续过程,或已经脱离了“网络”(即无法联系或没有回复电子邮件)。转让所有权的一个不好的原因是你不同意NIP的方向。我们努力围绕一个NIP去建立共识,如果你认为不可能达成,你可以提交一个更有说服力的NIP。

如果您对NIP的所有权感兴趣,请发送一封邮件要求接管,该邮件的收件人是原作者和NIP编辑。如果原作者没有及时回复邮件,NIP的编辑就会做出单方面的决定(这样的决定并不是不能逆转的)。

NIP编辑

当前的NIP编辑如下:

Niels <Niels@nuls.io>
Pen <Pen@nuls.io>

NIP编辑的职责

每次收到一个新的NIP, 一个编辑要做如下的事:

  • 阅读NIP来检查它是否较为完备,NIP中的想法必须具有技术意义,即使它们看起来不太可能达到最终状态。
  • 标题和内容要相符。
  • 检查NIP的语言(拼写、语法、句子结构等)、标记(Github风格的标记)、代码风格 。

如果NIP不够完备,编辑会把它发回给作者进行修改,并给出具体的说明。一旦NIP做好了合并到仓库的准备,NIP编辑就会这样做:

  • 分配一个NIP编号(通常是PR编号)

  • 合并相应的PR

  • 将消息发送回NIP作者

许多NIP是由对NULS代码库具有写入权限的开发人员编写和维护的。NIP编辑要关注NIP的变化,并纠正我们看到的任何结构、语法、拼写或标记错误。NIP编辑不会主观地对NIP做出判断,只做管理和编辑这部分工作。

History

这个文档主要引用了 Bitcoin’s BIP-0001,由 Amir Taaki 所写,同时他所写的文本也主要来源于 Python’s PEP-0001。NIP根据自身的实际情况,基于他们的文档做了一些修改,例如NIP流程中增加了理事会,修改了NIP类型等。后续与NIP相关的问题请直接联系NULS NIP的编辑。

​ ,