NXEP 0-目的和过程#
- 作者
贾罗德·米尔曼<millman@berkeley.edu>
- 状态
草稿
- 类型
过程
- 创建
2020-06-25
什么是NXEP？#
NXEP代表NetworkX增强建议。nxep是提出主要新特性、收集社区对某个问题的输入以及记录NetworkX中的设计决策的主要机制。NXEP应该提供特性的简明技术规范和特性的基本原理。NXEP作者负责在社区内建立共识并记录不同意见。
因为nxep在版本化的存储库中作为文本文件进行维护，所以它们的修订历史记录就是特性建议的历史记录 1.
类型#
nxep有三种：
A 标准轨道 NXEP描述NetworkX的新特性或实现。
安 信息 NXEP描述了NetworkX的设计问题，或者向Python社区提供了一般的指导原则或信息，但是没有提出新的特性。信息nxp不一定代表NetworkX社区的共识或建议，因此用户和实现者可以随意忽略信息nxp或遵循他们的建议。
A 过程 NXEP描述了NetworkX周围的进程，或者建议对进程（或进程中的事件）进行更改。进程nxep类似于标准Track nxep，但适用于NetworkX语言本身以外的其他领域。他们可能会提出一个实现方案，但不是NetworkX的代码库；他们需要社区的一致同意。示例包括过程、指南、决策过程的更改，以及NetworkX开发中使用的工具或环境的更改。任何meta-NXEP也被认为是一个进程NXEP。
NXEP工作流#
NXEP过程从NetworkX的新概念开始。强烈建议单个NXEP包含一个关键建议或新想法。小的增强或补丁通常不需要NXEP，可以通过对NetworkX的请求将其注入NetworkX开发工作流中 repo . NXEP越专注，就越容易成功。如果有疑问，把你的NXEP分成几个重点突出的部分。
每一个NXEP都必须有一个拥护者，他使用下面描述的风格和格式编写NXEP，在适当的论坛指导讨论，并试图围绕这个想法建立社区共识。NXEP拥护者（又称为作者）应该首先尝试确定这个想法是否适合NXEP。发布到networkx讨论 mailing list 是做这件事的最好方法。
提案应通过 GitHub pull request 到 doc/nxeps 具有名称的目录 nxep-<n>.rst 在哪里？ <n> 是一个适当分配的四位数字（例如。， nxep-0000.rst ). 草稿必须使用 NXEP X-模板和说明 文件。
一旦NXEP的PR到位，就应该在包含“向后兼容”部分的邮件列表中发布一篇文章，目的是将讨论限制在使用和影响上。关于pull请求的讨论范围将更广，还包括实现的细节。
应尽早合并PR（无论讨论期间是否接受）。作者可以制作额外的pr来更新或扩展NXEP，或者由维护人员设置其状态、讨论URL等。
标准跟踪nxep由两部分组成，一个设计文档和一个参考实现。通常建议至少与NXEP共同开发一个原型实现，因为原则上听起来不错的想法在进行实现测试时有时会变得不切实际。通常，将原型实现作为PR提供给NetworkX repo是有意义的（确保适当地将PR标记为WIP）。
审查和解决#
NXEP在邮件列表中讨论。nxep状态的可能路径如下：
所有nxep都应该用 Draft 状态。
最后，经过讨论，可能会达成一致意见，即应该接受NXEP–有关详细信息，请参阅下一节。此时状态变为 Accepted .
一旦NXEP Accepted ，必须完成引用实现。当引用实现完成并合并到主源代码存储库中时，状态将更改为 Final .
为了在保证语言特性或标准库API的长期稳定性之前收集额外的设计和接口反馈，NXEP也可以标记为“临时的”。这是“暂时接受”的缩写，表示建议已被接受以包含在参考实施中，但在整个设计被视为“最终”之前，还需要额外的用户反馈。与常规接受的nxep不同，即使在Python版本中包含了相关的更改，临时接受的nxep仍然可能被拒绝或撤回。
在可能的情况下，最好缩小建议的范围，以避免依赖“临时”状态（例如，将某些功能推迟到以后的nxp），因为这种状态可能会导致更广泛的NetworkX生态系统中的版本兼容性挑战。
也可以为NXEP分配状态 Deferred . 当NXEP没有进展时，NXEP作者或核心开发人员可以为NXEP分配此状态。
NXEP也可以是 Rejected . 也许说到底这不是个好主意。对这一事实进行记录仍然很重要。这个 Withdrawn 状态是相似的——这意味着NXEP的作者自己已经认为NXEP实际上是个坏主意，或者已经接受了一个竞争性的提议是一个更好的选择。
当NXEP是 Accepted ， Rejected 或 Withdrawn ，应相应地更新NXEP。除了更新status字段，至少 Resolution 邮件头应该添加到邮件列表档案中相关线程的链接。
nxep也可以 Superseded 通过一个不同的NXEP，使原始文件过时。这个 Replaced-By 和 Replaces 标题应该分别添加到原始和新的nxep。
进程nxep的状态也可以是 Active 如果它们从未打算完成，例如NXEP 0（此NXEP）。
NXEP如何被接受#
NXEP是 Accepted 经所有感兴趣的贡献者一致同意。我们需要一个具体的方法来判断是否达成了共识。当您认为NXEP可以接受时，请向networkx讨论邮件列表发送一封电子邮件，邮件主题如下：
接受NXEP的建议：
在电子邮件正文中，您应该：
链接到NXEP的最新版本，
简要描述任何主要争论点及其解决方法，
包括这样一句话：“如果在这封电子邮件发出后的7天内没有实质性的反对意见，那么NXEP将被接受；有关更多详细信息，请参阅NXEP 0。”
有关示例，请参见：https://mail.python.org/pipermail/networkx-discussion/2018-June/078345.html
在您发送电子邮件后，您应该确保从 Discussion NXEP的一部分，以便人们以后可以找到它。
一般来说，NXEP的作者将是发送此电子邮件的人，但任何人都可以这样做-重要的是确保每个人都知道NXEP何时即将被接受，并给他们最后一次回应的机会。如果有什么特别的理由把最后的评论期延长到7天以上，那没关系，只要在邮件里说出来。你不应该少于7天，因为有时人们是旅行或类似的，需要一些时间来回应。
总的来说，目标是确保社会各界有共识，而不是提供一个僵化的政策让人们去尝试博弈。当你有疑问的时候，错误的做法是寻求更多的反馈和寻求妥协的机会。
如果最后的评论期通过而没有任何实质性的反对意见，那么NXEP可以被正式标记 Accepted . 你应该发送一封后续邮件通知名单（庆祝表情图可选，但鼓励使用）🎉✨)，然后通过设置 :Status: 到 Accepted ，及其 :Resolution: 你的后续邮件链接的标题。
如果有 are 实质性异议，那么NXEP仍然存在 Draft 声明，讨论照常继续，一旦异议得到解决，可以再次提议接受。
在不寻常的情况下，有关方向或方法的分歧可能需要上报至网络X 指导委员会 谁来决定一个有争议的NXEP Accepted .
维护#
一般来说，标准跟踪nxep在达到最终状态后不再被修改，因为代码和项目文档被认为是实现特性的最终参考。但是，最终确定的标准跟踪nxep可能会根据需要进行更新。
过程nxep可能会随着时间的推移而更新，以反映对开发实践和其他细节的更改。在这些情况下遵循的精确过程将取决于正在更新的NXEP的性质和目的。
格式和模板#
nxep是UTF-8编码的文本文件，使用 reStructuredText 格式。请看 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的所有作者的姓名和可选的电子邮件地址。作者头值的格式必须是
随机J用户<地址@dom.ain>
如果包括电子邮件地址，并且
随机J用户
如果没有给出地址。如果有多个作者，每个作者都应该在单独的行上。