NXEP 0 — 目的和流程#

Author:: Jarrod Millman <millman@berkeley.edu>
Status:: 已接受
Type:: 流程
Created:: 2020-06-25

什么是NXEP？#

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

由于NXEP以文本文件的形式保存在一个版本化的存储库中，它们的修订历史是功能提案的历史记录 [1]。

类型#

有三种类型的NXEP：

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

NXEP工作流程#

NXEP流程始于对NetworkX的新想法。强烈建议一个NXEP包含一个关键提案或新想法。小的增强或补丁通常不需要NXEP，并可以通过向NetworkX的 repo 提交拉取请求将其注入到NetworkX的开发工作流中。NXEP越专注，成功的可能性就越大。如果有疑问，请将NXEP拆分为几个焦点明确的提案。

每个NXEP必须有一个负责人，即撰写使用下文描述的风格和格式的NXEP、引导适当论坛中的讨论并尝试围绕这一想法建立社区共识的人。NXEP负责人（又称作者）应首先尝试确定这个想法是否适合成为NXEP。发布到networkx-discussion `邮件列表`_ 是这样做的最佳方式。

提案应通过向 doc/nxeps 目录提交名为 nxep-<n>.rst 的GitHub拉取请求作为草稿NXEP提交，其中 <n> 是适当分配的四位数字（例如，: nxep-0000.rst )。草案必须使用:doc:nxep-template 文件。

一旦NXEP的PR就位，应该在邮件列表中发布一个帖子，其中包含直到“向后兼容性”部分的内容，目的是将讨论限制在使用和影响上。PR上的讨论范围将更广泛，还包括实现细节。

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

标准跟踪NXEP包括两部分，设计文档和参考实现。通常建议至少与NXEP同时开发原型实现，因为在实施测试时，有些在原则上听起来不错的想法有时会被证明是不切实际的。通常情况下，原型实现作为PR应该在NetworkX存储库中提供（确保适当地将PR标记为WIP）。

审查和解决#

NXEP在邮件列表上进行讨论。NXEP的状态可能有以下几种路径：

所有NXEP都应该以“草案”状态创建。

最终，在讨论之后，可能会达成一致意见，认为应该接受NXEP-有关详细信息，请参见下一节。此时状态变为“已接受”。

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

为了在承诺长期稳定性之前收集额外的设计和接口反馈，NXEP也可以被标记为“临时”。这是“暂时接受”的缩写，表示建议已被接受并包含在参考实现中，但在完整设计被视为“最终”之前需要额外的用户反馈。与常规接受的NXEP不同，暂时接受的NXEP即使在相关更改已包含在Python发布中后，仍可能被拒绝或撤回。

在可能的情况下，考虑将提案范围缩小以避免依赖“临时”状态（例如，通过将一些功能推迟到以后的NXEP），因为这种状态可能会导致在更广泛的NetworkX生态系统中出现版本兼容性挑战。

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

NXEP也可以被“拒绝”。也许说了这么多之后，这不是一个好主意。仍然重要的是要有这个事实的记录。“撤回”状态类似—这意味着NXEP作者他们已经决定NXEP实际上是一个坏主意，或者接受了一个竞争性提案作为更好的替代方案。

当一个NXEP被“接受”、“拒绝”或“撤回”时，应相应更新NXEP。除了更新状态字段外，至少应添加“Resolution”标题，其中包含指向邮件列表存档中相关线程的链接。

NXEP也可以被另一个NXEP“取代”，使原始NXEP变得过时。应分别在原始NXEP和新NXEP中添加“Replaced-By”和“Replaces”标题。

如果Process NXEP永远不打算完成，则其状态也可以为“Active”，例如NXEP 0（此NXEP）。

NXEP如何被接受#

通过所有感兴趣的贡献者的共识来“接受”NXEP。我们需要一种明确的方法来判断是否达成了共识。当您认为一个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可以正式标记为“已接受”。您应该发送一封跟进邮件通知列表（庆祝表情符号可选但鼓励使用🎉✨），然后通过将其“:Status:”设置为“Accepted”，并将其“:Resolution:”标题设置为指向您的跟进电子邮件的链接来更新NXEP。

如果*有*实质性异议，则NXEP仍处于“Draft”状态，讨论将继续进行，一旦异议解决，可以稍后再次提出接受。在不寻常的情况下，关于方向或方法的分歧可能会产生。需要升级到 NetworkX 指导委员会，然后由其决定是否接受有争议的 NXEP。

维护#

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

过程性的 NXEP 可以随时间更新以反映开发实践和其他细节的变化。在这些情况下遵循的具体流程将取决于更新的 NXEP 的性质和目的。

格式和模板#

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

头部前言#

每个 NXEP 必须以头部前言开头。头部必须按照以下顺序出现。带有 * 标记的头部是可选的。所有其他头部是必需的。:

  :Author: <作者的真实姓名列表，可选地包括电子邮件地址>
  :Status: <草案 | 活跃 | 已接受 | 推迟 | 拒绝 | 撤回 | 最终 | 被取代>
  :Type: <标准跟踪 | 过程>
  :Created: <创建日期，格式为 dd-mmm-yyyy>
* :Requires: <nxep 编号>
* :NetworkX-Version: <版本号>
* :Replaces: <nxep 编号>
* :Replaced-By: <nxep 编号>
* :Resolution: <url>

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

Random J. User <address@dom.ain>

如果包括电子邮件地址，如果不提供地址，则只需

Random J. User

如果有多个作者，每个作者应该单独一行。