NXEP 0 — 目的和流程#

作者：: Jarrod Millman <millman@berkeley.edu>
状态：: 已接受
类型：: 流程
创建日期：: 2020-06-25

什么是 NXEP？#

NXEP 代表 NetworkX 增强提案（NetworkX Enhancement Proposal）。NXEP 是提出主要新功能、收集社区对某个问题的意见以及记录 NetworkX 设计决策的主要机制。NXEP 应提供该功能的简洁技术规范和理由。NXEP 作者负责在社区内建立共识并记录不同意见。

由于 NXEP 以文本文件的形式保存在版本控制的仓库中，因此其修订历史记录就是功能提案的历史记录 [1]。

类型#

NXEPs 分为三种类型

标准追踪 NXEP 描述了 NetworkX 的新功能或实现。
信息性 NXEP 描述了 NetworkX 的设计问题，或向 Python 社区提供通用指南或信息，但不提出新功能。信息性 NXEP 不一定代表 NetworkX 社区的共识或建议，因此用户和实现者可以自由地忽略信息性 NXEP 或遵循其建议。
流程 NXEP 描述了围绕 NetworkX 的流程，或建议更改（或触发）某个流程中的事件。流程 NXEP 类似于标准追踪 NXEP，但适用于 NetworkX 语言本身之外的领域。它们可以提出实现建议，但不是针对 NetworkX 代码库的；它们需要社区共识。示例包括程序、指南、决策流程的变更以及 NetworkX 开发中使用的工具或环境的变更。任何元 NXEP 也被视为流程 NXEP。

NXEP 工作流程#

NXEP 流程始于 NetworkX 的新想法。强烈建议单个 NXEP 包含一个关键提案或新想法。小的增强或补丁通常不需要 NXEP，可以通过向 NetworkX 仓库提交拉取请求的方式注入到 NetworkX 开发工作流程中。NXEP 越聚焦，往往越成功。如果拿不准，请将你的 NXEP 分拆成几个重点明确的提案。

每个 NXEP 都必须有一个推动者——负责按照下述样式和格式撰写 NXEP、在适当的论坛引导讨论，并努力围绕该想法建立社区共识的人。NXEP 推动者（也称为作者）应首先尝试确定该想法是否适合作为 NXEP。向 networkx-discussion 邮件列表发帖是进行此操作的最佳方式。

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

一旦 NXEP 的 PR 就绪，应向邮件列表发布包含从头到“Backward compatibility”（向后兼容性）部分的帖子，目的是将该处的讨论限制在使用和影响方面。关于拉取请求的讨论范围将更广，也将包括实现细节。

在方便时，应尽快合并 PR（无论讨论中是否被接受）。作者可以提交额外的 PR 来更新或扩展 NXEP，或者维护者可以提交 PR 来设置其状态、讨论 URL 等。

标准追踪 NXEP 由两部分组成：设计文档和参考实现。通常建议与 NXEP 同时开发至少一个原型实现，因为原则上听起来不错的想法有时在实现测试时会变得不切实际。通常，将原型实现作为 PR 提供给 NetworkX 仓库（并确保将 PR 适当标记为 WIP，即进行中）是有意义的。

评审与决议#

NXEPs 在邮件列表中讨论。NXEP 的状态可能的路径如下所示

所有 NXEP 都应以 Draft（草稿）状态创建。

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

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

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

在可能的情况下，最好减少提案的范围，以避免依赖“临时”状态（例如，将某些功能推迟到后续 NXEP），因为这种状态可能导致更广泛的 NetworkX 生态系统中出现版本兼容性问题。

NXEP 也可以被分配状态 Deferred（已推迟）。当 NXEP 没有进展时，NXEP 作者或核心开发者可以给 NXEP 分配此状态。

NXEP 也可以被 Rejected（已拒绝）。也许说到底这不是一个好主意。记录这一事实仍然很重要。Withdrawn（已撤回）状态类似——这意味着 NXEP 作者自己认为该 NXEP 确实是个坏主意，或者承认竞争提案是更好的替代方案。

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

NXEPs 也可以被另一个 NXEP Superseded（已取代），使得原有的 NXEP 过时。应在原有的和新的 NXEP 中分别添加 Replaced-By（被取代者）和 Replaces（取代者）头部。

流程 NXEPs 如果从未打算完成，也可以处于 Active（活跃）状态，例如 NXEP 0（即本 NXEP）。

NXEP 如何被接受#

NXEP 经所有感兴趣的贡献者达成共识后被 Accepted（已接受）。我们需要一种具体的方法来判断是否已达成共识。当你认为某个 NXEP 已准备好被接受时，向 networkx-discussion 邮件列表发送一封主题类似于以下的电子邮件：

提议接受 NXEP #<编号>: <标题>

在你的电子邮件正文中，你应该

链接到 NXEP 的最新版本，
简要描述任何主要的争议点以及它们是如何解决的，
包含一句类似的话：“如果在收到此电子邮件后 7 天内没有实质性反对意见，则该 NXEP 将被接受；详情请参阅 NXEP 0。”

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

发送电子邮件后，应确保从 NXEP 的 Discussion（讨论）部分链接到该邮件主题，以便人们稍后查找。

通常由 NXEP 作者发送此电子邮件，但任何人都可以发送——重要的是确保每个人都知道某个 NXEP 即将获得接受，并给他们最后的机会进行回应。如果有什么特殊原因需要将此最终评论期延长超过 7 天，那没关系，只需在电子邮件中说明即可。不应少于 7 天，因为有时人们在旅行或有类似情况，需要一些时间进行回应。

总的来说，目标是确保社区达成共识，而不是提供僵化的政策供人们投机取巧。如有疑问，宁可多征求反馈，并寻找妥协的机会。

如果最终评论期过去没有实质性反对意见，则可以将该 NXEP 正式标记为 Accepted（已接受）。你应该发送一封后续电子邮件通知列表（庆祝表情符号可选，但鼓励使用 🎉✨），然后更新 NXEP，将其 :Status: 设置为 Accepted，并将其 :Resolution:（决议）头部设置为指向你后续电子邮件的链接。

如果确实存在实质性反对意见，则 NXEP 保持 Draft（草稿）状态，讨论照常继续，待反对意见解决后可以再次提议接受。

在特殊情况下，关于方向或方法的争议可能需要升级至 NetworkX 指导委员会，由他们决定有争议的 NXEP 是否被 Accepted（已接受）。

维护#

通常，标准追踪 NXEP 在达到最终状态后不再修改，因为代码和项目文档被视为已实现功能的最终参考。然而，最终确定的标准追踪 NXEPs 可以根据需要进行更新。

流程 NXEPs 可能会随着时间推移进行更新，以反映开发实践和其他细节的变化。这些情况下的具体流程将取决于正在更新的 NXEP 的性质和目的。

格式和模板#

NXEP 是使用 reStructuredText 格式的 UTF-8 编码文本文件。有关更多信息，请参阅 NXEP X — 模板和说明文件和 reStructuredTextPrimer。我们使用 Sphinx 将 NXEP 转换为 HTML 以便在 Web 上查看 [2]。

头部前导内容#

每个 NXEP 必须以头部前导内容开头。头部必须按以下顺序出现。标记为 * 的头部是可选的。所有其他头部都是必需的。

  :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: <nxep numbers>
* :NetworkX-Version: <version number>
* :Replaces: <nxep number>
* :Replaced-By: <nxep number>
* :Resolution: <url>

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

Random J. User <address@dom.ain>

如果包含电子邮件地址，如果未提供地址，则仅为

Random J. User

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