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 邮件列表是做到这一点的最佳方法。

该提案应通过 GitHub 拉取请求以 doc/neps 目录中的 nep-<n>.rst 的名称提交，其中 <n> 是一个适当分配的四位数字（例如，nep-0000.rst）。草案必须使用 NEP X — 模板和说明文件。

一旦 NEP 的 PR 到位，应在邮件列表中发布一个帖子，其中包含“向后兼容性”之前的部分，目的是将讨论限制在用法和影响方面。对拉取请求的讨论范围更广，还包括实现细节。

在最早的方便时间，应合并 PR（无论是在讨论期间是否被接受）。作者可以创建额外的 PR 来更新或扩展 NEP，或者维护者可以设置其状态、讨论 URL 等。

标准跟踪 NEP 由两部分组成，一个设计文档和一个参考实现。通常建议与 NEP 共同开发至少一个原型实现，因为在原理上看起来不错的一些想法在经过实现测试后可能被证明是不切实际的。通常，将原型实现作为对 NumPy 存储库的 PR 是有意义的（确保将 PR 标记为 WIP）。

审查和解决#

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

所有 NEP 都应以 草稿 状态创建。

最终，经过讨论，可能会达成共识，即应接受 NEP — 请参阅下一节了解详细信息。此时状态变为 已接受。

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

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

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

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

NEP 也可能被 拒绝。也许最终它不是一个好主意。仍然重要的是记录这一事实。撤回 状态与此类似——这意味着 NEP 作者自己认为 NEP 是一个坏主意，或者已经接受了竞争提案是一个更好的选择。

当 NEP 被 接受、拒绝 或 撤回 时，应相应地更新 NEP。除了更新状态字段之外，至少应添加 解决 标头，其中包含邮件列表存档中相关线程的链接。

NEP 也可能被另一个 NEP 取代，使原始 NEP 过时。应分别添加 Replaced-By 和 Replaces 标头，其中包含对原始和新 NEP 的引用，例如 :ref:`NEP#number`。

如果流程 NEP 永远不会完成，例如 NEP 0（此 NEP），它们也可能具有 活动 状态。

NEP 如何被接受#

NEP 通过所有感兴趣的贡献者的共识被 接受。我们需要一种具体的方法来判断共识是否已达成。当您认为 NEP 准备接受时，请向 numpy-discussion 邮件列表发送电子邮件，主题类似于

提案接受 NEP #<number>: <title>

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

链接到 NEP 的最新版本，
简要描述任何主要分歧以及如何解决它们，
包含类似于以下内容的句子：“如果在从此电子邮件开始的 7 天内没有实质性异议，则 NEP 将被接受；有关详细信息，请参阅 NEP 0。”

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

发送电子邮件后，您应该确保从 NEP 的“讨论”部分链接到电子邮件线程，以便人们以后可以找到它。

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

总的来说，目标是确保社区达成共识，而不是为人们试图玩游戏制定严格的政策。如有疑问，请务必寻求更多反馈，并寻找妥协的机会。

如果最终评论期结束时没有任何实质性异议，那么 NEP 可以正式标记为 已接受。您应该发送一封后续电子邮件通知列表（可选庆贺表情符号，但鼓励 🎉✨），然后更新 NEP，将其 :Status: 设置为 已接受，并将 :Resolution: 标头链接到您的后续电子邮件。

如果确实存在实质性异议，那么 NEP 保持 草稿 状态，讨论照常进行，并且可以在异议解决后稍后再次提出接受提案。

在特殊情况下，可能会要求 NumPy 指导委员会决定有争议的 NEP 是否 接受。

维护#

通常，标准跟踪 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

如果未提供地址。如果有多个作者，则每个作者都应单独成行。