NEP 0 — 目的和流程#

作者:

Jarrod Millman <millman@berkeley.edu>

状态:

活跃

类型:

流程

创建:

2017-12-11

什么是 NEP？#

NEP 代表 NumPy 增强提案。NEP 是一份设计文档，为 NumPy 社区提供信息，或描述 NumPy 或其流程或环境的新功能。NEP 应提供该功能的简洁技术规范和基本原理。

我们希望 NEP 成为提出主要新功能、收集社区对某个问题的意见以及记录 NumPy 中设计决策的主要机制。NEP 作者负责在社区内达成共识并记录异议。

由于 NEP 作为文本文件保存在版本控制的存储库中，因此它们的修订历史是功能提案的历史记录 [1]。

类型#

有三种类型的 NEP

  1. **标准跟踪** NEP 描述 NumPy 的新功能或实现。

  2. **信息性** NEP 描述 NumPy 设计问题，或为 Python 社区提供一般指南或信息，但不建议任何新功能。信息性 NEP 不一定代表 NumPy 社区的共识或建议，因此用户和实施者可以自由地忽略信息性 NEP 或遵循其建议。

  3. **流程** 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 状态的可能路径如下

_images/nep-0000.png

所有 NEP 应使用 Draft 状态创建。

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

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

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

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

NEP 也可以分配状态 Deferred。NEP 作者或核心开发人员可以在 NEP 没有取得进展时为 NEP 分配此状态。

NEP 也可以 Rejected。也许在一切都说完后，这不是一个好主意。记录这一事实仍然很重要。 Withdrawn 状态与此类似——这意味着 NEP 作者本人已决定 NEP 实际上是一个坏主意，或者已接受竞争提案是更好的替代方案。

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

NEP也可以被另一个不同的NEPSuperseded（取代），使原始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，以便在网络上查看[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

如果没有提供地址，则为：

如果有多个作者，则每个作者应另起一行。

参考文献和脚注#

本页面内容