NEP 0 — 目的和流程#
- 作者:
Jarrod Millman <millman@berkeley.edu>
- 状态:
活跃
- 类型:
流程
- 创建:
2017-12-11
什么是 NEP？#
NEP 代表 NumPy 增强提案。NEP 是一份设计文档，它为 NumPy 社区提供信息，或者描述 NumPy 或其流程或环境的新功能。NEP 应该提供该功能的简洁技术规范及其基本原理。
我们打算让 NEP 成为提出主要新功能、收集社区对某个问题的意见以及记录 NumPy 设计决策的主要机制。NEP 作者负责在社区内建立共识并记录不同意见。
因为 NEP 作为文本文件保存在版本控制的存储库中，所以它们的修订历史就是该功能提案的历史记录 [1]。
类型#
有三种类型的 NEP
**标准跟踪** NEP 描述了 NumPy 的新功能或实现。
**信息性** NEP 描述了 NumPy 的设计问题，或为 Python 社区提供一般性指南或信息，但不提出新功能。信息性 NEP 不一定代表 NumPy 社区的共识或建议，因此用户和实施者可以自由地忽略信息性 NEP 或遵循其建议。
**流程** NEP 描述了围绕 NumPy 的流程，或提出对流程的更改（或流程中的事件）。流程 NEP 类似于标准跟踪 NEP，但适用于 NumPy 语言本身以外的领域。它们可能会提出实现，但不是对 NumPy 的代码库；它们需要社区共识。例如，程序、指南、决策流程的更改以及 NumPy 开发中使用的工具或环境的更改。任何元 NEP 也被视为流程 NEP。
NEP 工作流程#
NEP 流程始于 NumPy 的一个新想法。强烈建议单个 NEP 包含单个关键提案或新想法。小的增强或补丁通常不需要 NEP，可以通过向 NumPy repo 发出拉取请求将其注入 NumPy 开发工作流程中。NEP 越集中，就越容易成功。如有疑问，请将您的 NEP 分割成几个重点突出的 NEP。
每个 NEP 必须有一个负责人——编写使用以下描述的风格和格式的 NEP 的人，负责在适当的论坛中引导讨论，并尝试在社区内建立对该想法的共识。NEP 负责人（又称作者）应首先尝试确定该想法是否适合 NEP。发帖到 numpy-discussion 邮件列表 是最好的方法。
该提案应作为草稿 NEP 通过 GitHub 拉取请求 提交到 doc/neps 目录，名称为 nep-<n>.rst，其中 <n> 是适当分配的四位数字（例如，nep-0000.rst）。草稿必须使用 NEP X — 模板和说明 文件。
一旦 NEP 的 PR 就位，就应该向邮件列表发布一篇文章，其中包含“向后兼容性”之前的部分，目的是将那里的讨论限制在使用和影响方面。拉取请求上的讨论将有更广泛的范围，还包括实现细节。
在最早方便的时候，PR 应该合并（无论它在讨论中是否被接受）。作者可以发出额外的 PR 来更新或扩展 NEP，或者维护者可以设置其状态、讨论 URL 等。
标准跟踪 NEP 由两部分组成：设计文档和参考实现。通常建议至少与 NEP 共同开发原型实现，因为从原则上听起来不错的想法在经过实现测试后有时会证明不切实际。通常，将原型实现作为 PR 提供给 NumPy repo 是有意义的（确保将 PR 适当地标记为 WIP）。
审查和决议#
NEP 在邮件列表中讨论。NEP 状态的可能路径如下所示
所有 NEP 都应以 草稿 状态创建。
最终，经过讨论后，可能会有共识认为应该接受 NEP——有关详细信息，请参阅下一节。此时，状态将变为 已接受。
一旦 NEP 被 接受，就必须完成参考实现。当参考实现完成并合并到主源代码存储库中时，状态将更改为 最终。
为了在承诺语言功能或标准库 API 的长期稳定性之前收集额外的设计和接口反馈，NEP 也可能被标记为“临时”。这是“临时接受”的简称，表示该提案已被接受纳入参考实现，但在可以考虑将完整设计视为“最终”之前，需要额外的用户反馈。与常规接受的 NEP 不同，即使在相关的更改已包含在 Python 版本中之后，临时接受的 NEP 也可能仍被拒绝或撤回。
在可能的情况下，最好减少提案的范围以避免依赖“临时”状态（例如，通过将某些功能推迟到以后的 NEP），因为此状态可能会导致更广泛的 NumPy 生态系统中的版本兼容性问题。
NEP 也可分配状态 延迟。当 NEP 没有取得进展时，NEP 作者或核心开发人员可以为 NEP 分配此状态。
NEP 也可能被 拒绝。也许在一切都说完之后，这不是一个好主意。记录这一事实仍然很重要。已撤回 状态与此类似——这意味着 NEP 作者本人已决定 NEP 实际上是一个坏主意，或者已经接受竞争性提案是更好的替代方案。
当 NEP 被 接受、拒绝 或 撤回 时，应相应地更新 NEP。除了更新状态字段外，至少应添加 决议 标头，其中包含指向邮件列表存档中相关主题的链接。
NEP 也可以被另一个 NEP Superseded（取代），使原 NEP 作废。应分别添加包含对原始和新 NEP 引用（例如 :ref:`NEP#number`）的 Replaced-By 和 Replaces 头。
如果流程型 NEP 从未打算完成，例如 NEP 0（本 NEP），其状态也可以为 Active（活跃）。
NEP 如何被接受#
NEP 通过所有相关贡献者的共识被 Accepted（接受）。我们需要一种具体的方法来判断是否达成共识。当您认为某个 NEP 准备好接受时，请向 numpy-discussion 邮件列表发送一封主题类似于以下内容的邮件：
提案接受 NEP #<编号>：<标题>
在邮件正文中，您应该：
链接到 NEP 的最新版本；
简要描述任何主要的争议点以及如何解决这些争议；
包含类似这样的句子：“如果从发送此邮件起 7 天内没有实质性异议，则该 NEP 将被接受；详情请参见 NEP 0。”
例如，请参见：https://mail.python.org/pipermail/numpy-discussion/2018-June/078345.html
发送邮件后，您应该确保从 NEP 的 Discussion（讨论）部分链接到邮件线程，以便人们以后可以找到它。
通常，NEP 作者将是发送此邮件的人，但任何人都可以这样做——重要的是要确保每个人都知道 NEP 何时即将被接受，并给他们最后一次回应的机会。如果有一些特殊原因需要将此最终评论期限延长超过 7 天，那么就可以了，只需在邮件中说明即可。您不应少于 7 天，因为有时人们在旅行或类似情况，需要一些时间来回应。
总的来说，目标是确保社区达成共识，而不是制定一项僵化的政策让人们试图钻空子。如有疑问，应倾向于寻求更多反馈并寻找妥协的机会。
如果最终评论期过去没有任何实质性异议，则可以正式将 NEP 标记为 Accepted（已接受）。您应该发送后续邮件通知列表（可选但鼓励使用庆祝表情 🎉✨），然后通过将其 :Status: 设置为 Accepted（已接受）及其 :Resolution: 头设置为指向您的后续邮件的链接来更新 NEP。
如果存在实质性异议，则 NEP 保持 Draft（草稿）状态，讨论照常继续，一旦异议得到解决，可以再次提议接受。
在特殊情况下，可以请求 NumPy 指导委员会 决定是否有争议的 NEP 是否 Accepted（已接受）。
维护#
通常，标准追踪型 NEP 在达到最终状态后不再修改，因为代码和项目文档被认为是已实现功能的最终参考。但是，可以根据需要更新最终确定的标准追踪型 NEP。
流程型 NEP 可能会随着时间的推移而更新，以反映开发实践和其他细节的变化。在这种情况下遵循的确切流程将取决于正在更新的 NEP 的性质和目的。
格式和模板#
NEP 是使用 reStructuredText 格式的 UTF-8 编码文本文件。有关更多信息，请参见 NEP X — 模板和说明 文件和 reStructuredTextPrimer。我们使用 Sphinx 将 NEP 转换为 HTML，以便在网上查看 [2]。
标题序言#
每个 NEP 都必须以标题序言开头。标题必须按以下顺序出现。标有 * 的标题是可选的。所有其他标题都是必需的。
:Author: <list of authors' real names and optionally, email addresses>
:Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Superseded>
:Type: <Standards Track | Process>
:Created: <date created on, in dd-mmm-yyyy format>
* :Requires: <nep numbers>
* :NumPy-Version: <version number>
* :Replaces: <nep number>
* :Replaced-By: <nep number>
* :Resolution: <url>
作者标题列出了 NEP 所有作者的姓名，以及可选的电子邮件地址。作者标题值的格式必须为：
Random J. User <[email protected]>
如果包含电子邮件地址，则为：
Random J. User
如果未提供地址，则为：
讨论#
参考文献和脚注#
版权#
本文件已进入公有领域。