SPEC 目的和流程

描述#

SPEC 流程旨在识别科学 Python 生态系统中项目之间共同关注的领域，并制定协作编写、社区采用的指导方针来解决这些问题。此类指南被称为 SPEC：科学 Python 生态系统协调文档。

具体而言，SPEC 流程的目的是

1. 帮助统一生态系统，方便用户和开发者；
2. 为项目提供有关技术问题或流程的指导；
3. 记录标准 API、开发工具和社区实践；以及
4. 促进整个生态系统对常见问题的讨论并制定共享解决方案。

生态系统中的项目具有一套现有的、多样化的提案流程和开发约束。SPEC 补充了这些：它们是一种鼓励共享实践并提高项目间体验统一性的机制。例如，SPEC 可以捕获既定的实践，以便新项目从中学习；或者它们可以提出作者认为将使整个生态系统受益的新实践。

项目自行决定是否采用任何给定的 SPEC——通常，这将通过团队共识来实现。SPEC 可能不适合每个项目，因此，并不期望所有项目都必须采用所有 SPEC。也就是说，SPEC 通过被多个项目采用而发挥其作用——并且它们的权威来自它们被采用的程度。

参与 SPEC 流程的参与者必须遵守我们的行为准则。

关键术语#

科学 Python 生态系统

生态系统是社区开发的 Python 项目的松散联合体，这些项目广泛用于科学研究，彼此之间可以很好地交互，并且遵循类似的开发、文档、测试等规范。

SPEC 核心项目

核心项目 是生态系统的一个小子集，由成熟的社区开发项目组成，这些项目 (a) 被大多数其他项目依赖，并且 (b) 负责审查、讨论、实施和认可 SPEC 文档。

SPEC 指导委员会

指导委员会 领导 SPEC 项目并管理 SPEC 流程，包括主持SPEC 讨论论坛、接受 SPEC 文档和维护 SPEC 流程文档。

SPEC 流程

SPEC 流程在本文件中以及相关的SPEC 指导委员会 和SPEC 核心项目 文档中进行了概述。此流程由指导委员会管理和监督，并与核心项目、社区成员和整个生态系统中的项目协作运作。

SPEC 文档

SPEC 文档为项目提供操作指南，并帮助协调生态系统，为用户和开发者提供更统一的体验。这些文档与核心项目和其他感兴趣的生态系统项目和社区成员协作开发。

格式#

SPEC 是使用Markdown 格式的 UTF-8 编码文本文件，存储在SPEC 存储库 中。SPEC 文档通过scientific-python.org 存储库 中的代码使用Hugo 转换为 HTML，并部署到https://scientific-python.cn/specs/。每个 SPEC 都有一个标题相同的相应讨论，任何人都可以在其中发表评论、提问或对现有评论进行投票。

实施#

指导委员会管理 SPEC 流程，并在整个流程中为贡献者提供指导。在本节中，我们概述了 SPEC 流程中的主要决策点，并提供了有关如何开始新的 SPEC 提案的指导。

决策点#

SPEC 在其开发和实施过程中会经历四个决策点：接受、发布、认可和采用。

graph LR

START[ ]--> |Propose| A[Accept]
A--> |Develop| B[Publish]
B--> |Canvass| C[Endorse]
C--> |Recommend| D[Adopt]

click A callback "Steering Committee Action"
click B callback "Author Action"
click C callback "Core Project Action"
click D callback "Ecosystem Action"

style START fill:#FFFFFF, stroke:#FFFFFF;

作者首先提出一个 SPEC，如新的 SPEC 提案中所述。接受 SPEC 的决定由指导委员会做出，此时它将被添加到SPEC 存储库 的主分支中，并清楚地标记为草稿。一旦 (a) 草稿编写清楚地解释了共同关注的领域和共享解决方案的一般方法，以及 (b) 有贡献者（至少来自两个核心项目）有兴趣参与新 SPEC 的工作并将其推广到他们的项目以及更广泛的社区，就会接受提出的 SPEC。更多详细信息可以在指导委员会文档中找到。

在接受阶段，作者与核心项目和感兴趣的社区成员协商，开发他们的 SPEC。这在一个协作和迭代的过程中完成，重点是确保 SPEC 具有广泛的适用性并可能被广泛采用。目的是大多数 SPEC 将有多个项目的作者，包括核心项目。一旦作者认为他们的 SPEC 完成，他们就会发布它，删除其草稿状态。

作者现在征求核心项目的项目意见，以便他们可以认可它。一旦 SPEC 获得认可，实质性更改需要所有认可的核心项目的批准。

一旦获得两个（或更多）核心项目的认可，SPEC 就推荐进行广泛采用。更多详细信息可以在核心项目文档中找到。各个项目根据自己的决策流程选择采用SPEC。每个 SPEC 在其生态系统采用部分描述了采用它的含义。生态系统项目可以在流程中的任何时间点采用 SPEC，但是，最好等到 SPEC 获得几个核心项目的认可，以确保 SPEC 已经过审查并且被认为足够稳定，可以进行广泛采用。一旦 SPEC 获得认可，它可能仍然会发展，但修改 SPEC 的障碍将大大增加（因为所有认可的项目都需要同意更改）。尽早采用 SPEC 的项目应参与导致核心项目认可 SPEC 的协作流程，以确保其用例已被纳入。

徽章#

项目可以使用 SPEC 徽章突出显示其对特定 SPEC 的采用。例如，对于 SPEC 0，我们建议使用

或者，您可以使用一个徽章来指示对多个 SPEC 的采用。例如，要指示对 SPEC 0、1 和 4 的采用，我们建议使用以下方法

新的 SPEC 提案#

一个好的 SPEC 提案侧重于协调科学 Python 生态系统中项目的单个关键建议或想法。在提出 SPEC 之前，我们强烈建议您首先审查该想法，方法是执行以下一项或多项操作

1. 与生态系统中的至少一个项目讨论该想法，
2. 与生态系统的至少另一名成员讨论该想法，或
3. 创建一个最小的概念验证原型。

在接受提出的 SPEC 之前，必须在SPECS/Ideas 主题下的讨论论坛上讨论该想法。此后，必须作为拉取请求提交到SPEC 存储库中的新 SPEC 文档。

使用quickstart.py脚本创建新的 SPEC 文档。该脚本位于SPEC 存储库的顶层，它会询问您一些问题¹，然后创建一个新文件，并使用您需要完成的基本模板对其进行适当命名（例如，spec-0000/index.md）。一旦 SPEC 处于合理的状态，请针对SPEC 存储库提交拉取请求。然后，指导委员会会考虑拉取请求中提供的 SPEC，并提供其他指导。

注释#