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，或者由维护者来设置其状态、讨论 URL 等。

标准跟踪 NEP 由两部分组成：设计文档和参考实现。通常建议至少与 NEP 同时开发一个原型实现，因为在原则上听起来不错的想法，在经过实现测试后有时会变得不切实际。通常，将原型实现作为 PR 提供给 NumPy 仓库是明智之举（请务必将 PR 适当标记为 WIP）。

审阅与决议#

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

所有 NEP 都应以 Draft（草案）状态创建。

最终，经过讨论，可能会达成共识，认为 NEP 应该被接受——详见下一节。此时状态变为 Accepted（已接受）。

一旦 NEP 被 Accepted（已接受），必须完成参考实现。当参考实现完成并整合到主源代码仓库中时，状态将变为 Final（最终）。

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

在可能的情况下，最好缩小提案范围，以避免依赖“Provisional”（临时）状态（例如，通过将某些功能推迟到后续 NEP），因为这种状态可能导致更广泛的 NumPy 生态系统中出现版本兼容性挑战。

NEP 还可以被分配 Deferred（已推迟）状态。当 NEP 没有进展时，NEP 作者或核心开发人员可以为其分配此状态。

NEP 也可以被 Rejected（拒绝）。也许最终发现它不是一个好主意。记录这一事实仍然很重要。Withdrawn（撤回）状态类似——这意味着 NEP 作者自己决定该 NEP 实际上是个坏主意，或者接受了一个竞争提案是更好的替代方案。

当 NEP 被 Accepted（接受）、Rejected（拒绝）或 Withdrawn（撤回）时，应相应地更新 NEP。除了更新状态字段外，至少应添加 Resolution（决议）标题，并附上邮件列表存档中相关线程的链接。

NEP 也可以被不同的 NEP Superseded（取代），使原有的 NEP 过时。应分别添加包含原始和新 NEP 引用的 Replaced-By（被取代）和 Replaces（取代）标题，例如 :ref:`NEP#number`。

流程 NEP 如果从未打算完成，也可以具有 Active（活跃）状态，例如 NEP 0（本 NEP）。

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 一旦达到 Final（最终）状态后，通常不再进行修改，因为代码和项目文档被视为已实现功能的最终参考。但是，已定稿的标准跟踪 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>

Author（作者）标题列出了所有 NEP 作者的姓名，以及可选的电子邮件地址。Author 标题值的格式必须是：

Random J. User <[email protected]>

如果包含电子邮件地址，则为，而如果

Random J. User

不提供地址时则为。如果有多位作者，每位作者应单独占一行。