ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

NetworkX NXEP 提案机制全解析:从目的、流程到状态机与模板规范

NetworkX NXEP 提案机制全解析:从目的、流程到状态机与模板规范 NetworkX NXEP 提案机制全解析从目的、流程到状态机与模板规范【免费下载链接】networkxNetwork Analysis in Python项目地址: https://gitcode.com/gh_mirrors/ne/networkx导读NXEPNetworkX Enhancement ProposalNetworkX 增强提案是 NetworkX 社区用于提出重大新特性、收集社区意见、并沉淀设计决策的核心机制。本文以 doc/developer/nxeps/nxep-0000.rst 为骨架系统讲解 NXEP 的三种类型、完整工作流、状态流转规则、达成共识Accepted的规范步骤以及每个 NXEP 必须遵循的头部字段与正文模板。读完本文你将能够理解 NetworkX 社区以提案驱动重大变更的协作模式掌握提交一份合规 NXEP 的全部操作细节并能在实际贡献中正确选用 Draft / Accepted / Final / Provisional / Deferred / Rejected / Withdrawn / Superseded / Active 等状态。NXEP 状态流转示意图NXEP 是什么NetworkX 的设计决策载体NXEP 全称NetworkX Enhancement Proposal。根据 NXEP 0 的定义NXEP 是 NetworkX 提出重大新特性、收集社区意见、记录设计决策的主要机制。一份 NXEP 应当提供该特性的简明技术规范concise technical specification该特性的设计理由rationale。NXEP 的作者负责在社区内建立共识并把反对意见dissenting opinions一并记录下来而不是只呈现支持的声音。一个容易被忽视但极其重要的特性是NXEP 以文本文件形式维护在带版本管理的仓库中因此其修订历史天然成为该特性提案的历史档案——任何人都可以通过常规的 git 命令检索旧版本追溯一项设计从最初想法到最终落地的完整演化过程。NXEP 的三种类型NXEP 并非只有一种形态社区将提案分为三类类型描述关键约束Standards Track标准追踪描述 NetworkX 的新特性或新实现必须附带参考实现通常与 NXEP 同步开发Informational信息类描述 NetworkX 设计问题或向 Python 社区提供通用指南/信息但不提出新特性不一定代表社区共识用户和实现者可自由采纳或忽略Process流程类描述围绕 NetworkX 的流程或提出对流程的变更/事件与 Standards Track 类似但作用于代码库之外的领域可提出实现但不对 NetworkX 代码库生效需要社区共识任何 meta-NXEP 也归为 Process 类Process 类 NXEP 的典型例子包括开发流程规范、指南、决策过程的变更、开发工具与环境的变更。例如仓库中的 NXEP 1 — Governance and Decision Making 就是一份Type: Process的提案它定义了社区、贡献者、核心开发者与指导委员会Steering Council的角色与决策机制。NXEP 工作流从想法到正式提案起点一个聚焦的想法NXEP 流程始于一个关于 NetworkX 的新想法。官方强烈建议一份 NXEP 只包含一个关键提案或新想法。小而美的增强或补丁通常不需要NXEP直接通过 Pull Request 注入 NetworkX 开发流程即可。提案越聚焦越容易成功拿不准时宁可把一份 NXEP 拆成若干份聚焦的提案。关键角色Champion倡导者/作者每份 NXEP 都必须有一名champion其职责是使用规范格式撰写 NXEP在合适的论坛引导讨论围绕想法建立社区共识。Champion 在动笔之前应当先判断该想法是否适合走 NXEP 流程——最佳做法是先在 networkx-discussion 邮件列表中发帖征询意见。提交以 Draft 形式提交 PR提案应以Draft草稿形式提交通过 GitHub Pull Request 提交到doc/nxeps目录在本文档所在仓库中对应 doc/developer/nxeps/文件命名为nxep-n.rst其中n是分配的四位数字编号例如nxep-0000.rst草稿必须使用 NXEP 模板 撰写。提交后的讨论分工一旦 NXEP 的 PR 就位需要向邮件列表发送一份帖子内容包含从开头到 Backward compatibility 之前的所有章节目的是把该处的讨论限定在用法与影响层面而 PR 上的讨论范围更广可以涵盖实现细节。值得注意的是PR 应尽早合并无论讨论期间是否被接受后续由作者通过更多 PR 更新/扩充 NXEP或由维护者设置其状态、讨论 URL 等。Standards Track 的特殊要求参考实现Standards Track NXEP 由两部分组成设计文档参考实现reference implementation。官方推荐至少让原型实现与 NXEP 同步开发因为听起来不错的主意往往在实现检验下暴露问题。常见做法是把原型实现作为对 NetworkX 仓库的 PR 提供并在 PR 上恰当标注 WIP即 Work In Progress。Review and ResolutionNXEP 状态机全解NXEP 的状态流转是理解该机制的核心。上方图示给出了完整的状态转换关系本节结合 nxep-0000.rst 的文字说明逐一展开。Draft草稿——所有 NXEP 的起点所有 NXEP 创建时都应处于Draft状态。草稿是唯一可以自由修改的初始形态讨论期间的修订都在此状态进行。Accepted已接受经过讨论后若社区形成共识认为 NXEP 应当被接受状态变为Accepted。达成接受的具体判定程序见下文专节。Provisional暂行接受在承诺长期稳定性之前为了收集额外的设计与接口反馈NXEP 可被标记为Provisional即 Provisionally Accepted 的缩写。它表示提案已被接受纳入参考实现但在完整设计被视为 Final 之前仍需要更多用户反馈。与常规 Accepted 不同Provisional 状态的 NXEP即使相关改动已经合入发布版本仍可能被 Rejected 或 Withdrawn。因此官方建议只要可行应尽量缩小提案范围以避免依赖 Provisional 状态例如把部分特性推迟到后续 NXEP因为该状态可能在更广泛的 NetworkX 生态中引发版本兼容挑战。从图上可以看到Draft 可直接进入 ProvisionalAccepted 也可转入 Provisional虚线表示非强制路径Provisional 测试通过后转 Final、失败则被 Rejected。Final最终一旦 NXEP 被Accepted参考实现必须完成当参考实现完整并合入主源码仓库后状态改为Final。Deferred推迟当提案没有任何进展时NXEP 作者或核心开发者可将其标记为Deferred。被推迟的提案可以重新回到草稿状态图上 Draft ↔ Deferred 为双向箭头择机再启。Rejected 与 Withdrawn拒绝与撤回Rejected讨论结束后被认为不是好主意。记录这一事实同样重要。Withdrawn类似但区别在于作者本人决定该提案不成立或接受竞争提案是更好的替代方案。Superseded被取代一份 NXEP 可能被另一份 NXEPSuperseded使原提案作废。此时应在原 NXEP添加Replaced-By头部在新 NXEP添加Replaces头部形成双向引用链。Active活跃Process 类 NXEP 如果本就不打算完结可保持Active状态——NXEP 0 自身即是一例:Status: Accepted的同时它是定义流程的 Process 提案。状态变更时的收尾义务当 NXEP 变为Accepted、Rejected或Withdrawn时应同步更新 NXEP除更新状态字段外至少要添加Resolution头部并链接到邮件列表归档中的相关讨论线程。如何达成 Accepted七天的最终评论期社区需要一个具体标准来判断共识是否达成。NXEP 0 给出了可操作的完整程序第一步发送接受提案邮件当你认为 NXEP 已准备好被接受时向 networkx-discussion 邮件列表发送一封主题为以下格式的邮件Proposal to accept NXEP #number: title邮件正文必须包含三要素链接到最新版本的 NXEP简要描述主要的争议点及其解决方式包含类似这样的一句话If there are no substantive objections within 7 days from this email, then the NXEP will be accepted; see NXEP 0 for more details.若 7 天内无实质性反对NXEP 将被接受详见 NXEP 0。第二步链接讨论线程发送邮件后务必把该邮件线程链接到 NXEP 的Discussion章节方便后人检索。第三步等待并裁决通常由 NXEP 作者发送此邮件但任何人都可以——关键是让所有人知道 NXEP 正处于接受边缘并给予最后一次回应机会最终评论期不得少于 7 天有人可能正在出差或需要时间回应若确有特殊原因需要延长在邮件中说明即可若 7 天内无实质性反对即可正式标记为Accepted发送跟进邮件通知列表庆祝 emoji 可选但鼓励 ✨并将 NXEP 的:Status:更新为Accepted、:Resolution:头部链接到跟进邮件若存在实质性反对NXEP 保持在Draft状态继续讨论待反对解决后可再次提议接受该流程的核心精神是目标是确保社区共识而不是提供可被钻空子的僵化政策拿不准时宁可多征求反馈、寻找妥协机会。升级路径指导委员会裁决在罕见情况下方向或方法上的分歧可能需要升级到 NetworkX 指导委员会Steering Council裁决。关于 SC 的角色定义与决策机制可参见 NXEP 1 — Governance and Decision Making当核心开发者社区无法在合理时间内达成共识时SC 是解决争议的实体若 SC 内部仍僵持则提案在获得 SC 简单多数支持时向前推进。MaintenanceFinal 之后还能改吗Standards Track NXEP原则上在达到Final状态后不再修改因为代码与项目文档被视为已实现特性的最终参考但已定稿的 Standards Track NXEP 仍可按需更新。Process NXEP可随时间更新以反映开发实践与其他细节的变化具体流程取决于被更新 NXEP 的性质与目的。格式与模板一份合规 NXEP 的硬性规范文件格式与技术栈NXEP 是UTF-8 编码的文本文件使用reStructuredText格式项目使用Sphinx将 NXEP 转换为 HTML 供网页浏览写作时请参考 NXEP 模板。头部 Preamble字段顺序与必选性每份 NXEP必须以头部 preamble 开始字段必须按以下顺序出现。带*标记的为可选其余均为必选: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: urlAuthor 字段格式列出所有作者的真实姓名可附邮箱。含邮箱时格式为Random J. User addressdom.ain不含时仅为Random J. User多位作者时每人独占一行。以 NXEP 0 自身为例其头部为:Author: Jarrod Millman millmanberkeley.edu :Status: Accepted :Type: Process :Created: 2020-06-25正文模板八个标准章节NXEP 模板 定义了正文的标准结构每个章节都有明确的写作意图章节写作要求Abstract简述 NXEP 将要达成的目标注意模板标题中的破折号是长破折号—而非连字符-Motivation and Scope描述现有问题、受影响人群、要解决的问题及原因必须明确说明变更的范围与关键需求Usage and Impact从 NetworkX 用户视角描述新特性将如何使用主要由没有该 NXEP 就无法写出的代码示例构成并说明对生态的影响仅在必要时包含实现细节Backward compatibility描述该 NXEP 破坏向后兼容性的方式邮件列表帖只包含到本节为止的内容为不关心技术细节的用户提供高层摘要Detailed description详细描述变更包含新功能用法示例、预期用例与说明用法的伪代码Related Work列出相关/相似技术可能在其他库中不必面面俱到列出主要的先例即可Implementation列出实现的主要步骤尽量标注步骤间依赖、可省略步骤并随实现进展链接相关 PRNXEP 不要求用单个 PR 实现可分阶段落地Alternatives讨论其他解决方案及其取舍并说明选定方案的理由Discussion可仅包含链接到相关讨论邮件列表线程或 GitHub issue的列表NXEP 在仓库中的实际组织在 doc/developer/nxeps/ 目录下NXEP 以编号文档的形式集中存放index.rst —— NXEP 列表页通过 toctree 聚合全部 NXEP 文档并隐藏收纳模板页nxep-0000.rst —— 本文档即流程与目的的定义本身Process 类nxep-0001.rst —— Governance and Decision MakingProcess 类定义了社区角色与共识决策机制其中包含 Steering Council 的说明nxep-0002.rst —— API design of view slicesStandards Track 类为G.nodes/G.edges返回的 View 类提案切片支持展示了设计文档 参考实现的典型形态nxep-0003.rst、nxep-0004.rst —— 后续编号提案持续记录项目重大设计决策nxep-template.rst —— 新提案必须遵循的模板文件_static/nxep-0000.png —— 状态流转图资源。从仓库结构可以推断NXEP 机制本身仍在持续运转任何重大变更无论是新 API 设计还是流程调整都会以编号提案的形式沉淀在这里形成 NetworkX 设计与治理的权威史料。对于希望深度参与 NetworkX 开发的贡献者而言阅读现有 NXEP、理解其状态流转是把握项目设计脉络与决策文化的最直接入口。【免费下载链接】networkxNetwork Analysis in Python项目地址: https://gitcode.com/gh_mirrors/ne/networkx创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表