NEP 0 — 目的和流程#

作者:: Jarrod Millman <millman@berkeley.edu>
状态:: 活跃
类型:: 流程
创建日期:: 2017-12-11

什么是 NEP？#

NEP 是 NumPy 增强提案（NumPy Enhancement Proposal）的缩写。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。向 numpy-discussion 邮件列表发帖是实现此目的的最佳方式。

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

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

在最早方便时，应合并该拉取请求（无论在讨论中是否被接受）。作者可以提交额外的拉取请求来更新或扩展 NEP，维护者也可以提交请求来设置其状态、讨论 URL 等。

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

审查与决议#

NEP 状态的可能路径如下

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

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

一旦 NEP 被 接受（Accepted），必须完成参考实现。当参考实现完成并并入主源代码仓库后，状态将更改为 最终（Final）。

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

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

NEP 也可以被分配 延期（Deferred） 状态。当 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 如果从未打算完成，也可以具有 活跃（Active） 状态，例如 NEP 0（此 NEP）。

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）。您应该发送一封后续电子邮件通知列表（庆祝表情符号可选但鼓励添加 🎉✨），然后通过将其 :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

如果未提供地址。如果有多个作者，每个作者应单独占一行。