NEP 0 — 目的和过程#

作者：: 贾罗德·米尔曼 <米尔曼@伯克利。教育>
地位：: 积极的
类型：: 过程
创建：: 2017-12-11

什么是新经济政策？#

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。发布到 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。

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

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

为了在致力于语言功能或标准库 API 的长期稳定性之前收集额外的设计和界面反馈，NEP 也可能被标记为“临时”。这是“暂时接受”的缩写，表示该提案已被接受并包含在参考实现中，但在完整设计被视为“最终”之前，还需要额外的用户反馈。与常规接受的 NEP 不同，即使相关更改已包含在 Python 版本中，临时接受的 NEP 仍可能被拒绝或撤回。

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

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

NEP 也可以Rejected。也许归根结底这不是一个好主意。记录这一事实仍然很重要。状态Withdrawn是相似的——这意味着新经济政策作者自己已经认为新经济政策实际上是一个坏主意，或者已经接受竞争提案是一个更好的选择。

当 NEP 为Accepted、Rejected、或时Withdrawn，应相应更新 NEP。除了更新状态字段之外，至少Resolution应该在标题中添加指向邮件列表档案中相关线程的链接。

NEP 也可以Superseded由不同的 NEP 组成，从而使原始的 NEP 变得过时。应分别添加包含对原始 NEP 和新 NEP 的引用的 Replaced-By和标头。Replaces:ref:`NEP#number`

Active如果进程 NEP 永远不会完成，则它们也可能具有状态，例如 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

发送电子邮件后，您应该确保链接到DiscussionNEP 部分的电子邮件线程，以便人们稍后可以找到它。

一般来说，NEP 作者将是发送这封电子邮件的人，但任何人都可以这样做 - 重要的是确保每个人都知道 NEP 何时即将被接受，并给他们最后的回应机会。如果有特殊原因需要将最终意见征询期延长至 7 天以上，也可以，只需在电子邮件中说明即可。您不应少于 7 天，因为有时人们正在旅行或类似情况，需要一些时间来回复。

总的来说，目标是确保社区达成共识，而不是提供僵化的政策让人们尝试博弈。如有疑问，最好寻求更多反馈并寻找妥协的机会。

如果最终评议期过go且没有任何实质性异议，则 NEP 可以正式被标记Accepted。您应该发送一封后续电子邮件来通知该列表（庆祝表情符号可选，但鼓励??????✨），然后通过将其设置:Status: 为来更新 NEP Accepted，并将其:Resolution:标题设置为指向后续电子邮件的链接。

如果有实质性反对意见，则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 所有作者的姓名以及可选的电子邮件地址。 Author 标头值的格式必须是

Random J. User <[email protected]>

如果包含电子邮件地址，并且只是

Random J. User

如果没有给出地址。如果有多个作者，每个作者都应该占一行。