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 的存储库提交拉取请求注入到 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，或者维护者可以进行 PR 来设置其状态、讨论 URL 等。

标准轨道 NEP 由两部分组成，设计文档和参考实现。通常建议至少与 NEP 共同开发原型实现，因为原则上听起来不错的想法在经过实现测试后有时会被证明不切实际。通常，将原型实现作为 PR 提供给 NumPy 存储库是有意义的（确保将 PR 适当地标记为 WIP）。

审查和决议#

NEP 在邮件列表中进行讨论。NEP 状态的可能路径如下

所有 NEP 应该以 Draft 状态创建。

最终，经过讨论，可能会达成共识，NEP 应该被接受——有关详细信息，请参见下一节。此时，状态将变为 Accepted。

一旦 NEP 被 Accepted，参考实现必须完成。当参考实现完成并被合并到主源代码存储库中时，状态将更改为 Final。

为了在承诺语言功能或标准库 API 的长期稳定性之前收集额外的设计和接口反馈，NEP 也可能被标记为“Provisional”。这是“Provisionally Accepted”的简写，表示该提案已被接受并纳入参考实现，但需要额外的用户反馈才能将完整的设计视为“Final”。与常规的已接受 NEP 不同，即使在相关更改已包含在 Python 版本中之后，暂定接受的 NEP 仍然可能被拒绝或撤回。

在可能的情况下，最好减少提案的范围以避免依赖于“Provisional”状态（例如，通过将某些功能推迟到后面的 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 #<number>: <title>

在您的电子邮件正文中，您应该

链接到 NEP 的最新版本，
简要描述任何主要的分歧点以及如何解决它们，
包含类似的句子：“如果从这封电子邮件发送之日起 7 天内没有实质性异议，则 NEP 将被接受；有关更多详细信息，请参见 NEP 0。”

例如，请参见：https://mail.python.org/pipermail/numpy-discussion/2018-June/078345.html

在您发送电子邮件后，您应该确保从 NEP 的 Discussion 部分链接到电子邮件主题，以便人们以后可以找到它。

通常，NEP 作者将是发送此电子邮件的人，但任何人都可以发送——重要的是要确保每个人都知道 NEP 即将被接受，并给他们最后一次机会做出回应。如果由于特殊原因需要将最后评论期延长超过 7 天，那么这样做就可以了，请在电子邮件中说明。您不应该少于 7 天，因为有时人们会旅行或类似情况，需要一些时间来做出回应。

总的来说，目标是确保社区达成共识，而不是提供一种僵化的政策供人们试图利用。如有疑问，请在寻求更多反馈和寻找妥协机会方面谨慎行事。

如果最后评论期过去后没有实质性异议，那么 NEP 可以正式标记为 Accepted。您应该发送一封后续电子邮件通知邮件列表（可选但鼓励使用庆祝表情符号 🎉✨），然后通过将 NEP 的 :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

如果未给出地址。如果有多个作者，则每个作者应另起一行。