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 邮件列表 是实现此目的的最佳方法。
该提案应通过 GitHub 拉取请求 提交为草案 NEP 到 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 都应以 Draft 状态创建。
最终，经过讨论后，可能会达成共识，即应接受 NEP——有关详细信息，请参阅下一节。此时，状态将变为 Accepted。
一旦 NEP 被 Accepted，则必须完成参考实现。当参考实现完成并合并到主源代码存储库中时，状态将更改为 Final。
为了在致力于语言特性或标准库 API 的长期稳定性之前收集额外的设计和接口反馈，NEP 也可以标记为“临时”。这是“临时接受”的缩写，表示该提案已被接受纳入参考实现，但在设计完全被认为是“最终”之前，需要额外的用户反馈。与常规已接受的 NEP 不同，即使在相关的更改已包含在 Python 版本中之后，临时接受的 NEP 仍可能被拒绝或撤回。
尽可能地，建议缩小提案的范围以避免依赖“临时”状态（例如，通过将某些功能推迟到以后的 NEP），因为此状态可能会导致更广泛的 NumPy 生态系统中的版本兼容性问题。
NEP 也可以被赋予 Deferred 状态。当 NEP 没有进展时，NEP 作者或核心开发者可以将 NEP 赋予此状态。
NEP 也可以被 Rejected（拒绝）。也许经过一番考量后，它并非一个好主意。但记录下这一事实仍然很重要。Withdrawn（撤回）状态与此类似——这意味着 NEP 作者本人已决定该 NEP 实际上是个坏主意，或者已接受竞争性提案是更好的替代方案。
当 NEP 被 Accepted（接受）、Rejected（拒绝）或 Withdrawn（撤回）时，应相应地更新 NEP。除了更新状态字段外，至少应添加 Resolution（决议）标题，其中包含指向邮件列表存档中相关主题的链接。
NEP 也可以被另一个 NEP Superseded（取代），使原 NEP 作废。应分别添加包含对原始 NEP 和新 NEP 的引用的 Replaced-By（被…取代）和 Replaces（取代…）标题，例如 :ref:`NEP#number`。
如果流程型 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，以便在 Web 上查看 [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
如果未提供地址，则为：
讨论#
参考文献和脚注#
版权#
本文档已进入公共领域。