跳过 0 — 目的和过程#

作者:: Jarrod Millman <millman@berkeley.edu>
作者:: Juan Nunez-Iglesias <juan.nunez-iglesias@monash.edu>
作者:: Stéfan van der Walt <stefanv@berkeley.edu>
状态:: 活跃
类型:: 过程
创建:: 2019-07-30

什么是 SKIP？#

SKIP 代表 scikit-image proposal。一个 SKIP 是一个设计文档，为社区提供信息，或描述 scikit-image 的新功能、流程或环境。SKIP 应提供所提议更改的理由，并在适用情况下提供简明的技术规范。

我们打算将 SKIPs 作为提出重大新功能、收集社区对某个问题的意见以及记录 scikit-image 设计决策的主要机制。SKIP 的作者负责在社区内建立共识并记录不同意见。

因为 SKIPs 作为文本文件保存在版本控制的仓库中，它们的修订历史就是功能提案的历史记录 [1]。

类型#

有三种 SKIP：

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

SKIP 工作流程#

SKIP 过程始于 scikit-image 的一个新想法。一个 SKIP 应包含一个关键提案或新想法。小的增强或补丁通常不需要 SKIP，可以通过向 scikit-image repo 提交拉取请求来注入 scikit-image 开发工作流。SKIP 越专注，被接受的可能性就越大。

每个 SKIP 必须有一个倡导者——一个使用下面描述的风格和格式编写 SKIP 的人，在适当的论坛中引导讨论，并尝试围绕这个想法建立社区共识。SKIP 倡导者（又名作者）应首先尝试确定该想法是否适合作为 SKIP。在 scikit-image 开发者论坛上发布是最好的方式。

提案应以草稿 SKIP 的形式通过 GitHub pull request 提交到 doc/source/skips 目录，文件名为 skip-<n>.rst，其中 <n> 是一个适当分配的编号（例如，skip-35.rst）。草稿必须使用跳过 X — 模板和说明文件。

一旦PR到位，应在开发者论坛上宣布SKIP以供讨论（PR本身的评论应仅限于小的编辑和技术修复）。

在最早的方便时间，PR 应该被合并（无论在讨论期间是否被接受）。一个概述了连贯论点并且被认为合理完整的 SKIP 应该乐观地合并，无论在讨论期间是否被接受。作者可以提交额外的 PR 来更新或扩展 SKIP，或者维护者可以提交 PR 来设置其状态、讨论 URL 等。

标准跟踪 SKIP 由两部分组成，一个设计文档和一个参考实现。通常建议至少与 SKIP 同时开发一个原型实现，因为理论上听起来不错的想法有时会证明是不切实际的。通常，只要正确标记为 WIP（正在进行的工作），原型实现作为 PR 提供给 scikit-image 仓库是有意义的。

审查与决议#

SKIPs 在开发者论坛上进行了讨论。SKIPs 状态的可能路径如下：

所有 SKIP 应以 Draft 状态创建。

最终，经过讨论，可能会达成共识，即应接受 SKIP – 详情请参见下一节。此时，状态变为 Accepted。

一旦 SKIP 被 接受，参考实现必须完成。当参考实现完成并被纳入主源代码库时，状态将更改为 最终。

为了在承诺语言特性或标准库API的长期稳定性之前收集额外的设计和接口反馈，一个SKIP也可以被标记为“Provisional”。这是“Provisionally Accepted”的缩写，表示该提案已被接受并包含在参考实现中，但在设计被视为“Final”之前，还需要额外的用户反馈。与常规接受的SKIPs不同，即使相关更改已包含在发布中，暂时接受的SKIPs仍可能被拒绝或撤回。

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

一个 SKIP 也可以被分配状态 Deferred。当 SKIP 上没有进展时，SKIP 作者或核心开发者可以为此 SKIP 分配此状态。

一个 SKIP 也可以被 拒绝。或许在所有都说完做过后，这并不是一个好主意。记录这一事实仍然很重要。撤回 状态与此类似——这意味着 SKIP 的作者自己决定 SKIP 实际上是一个坏主意，或者已经接受了一个竞争提案是更好的替代方案。

当一个 SKIP 被 接受、拒绝 或 撤回 时，SKIP 应相应地更新。除了更新状态字段外，至少应添加 决议 标题，并附上讨论论坛上相关帖子的链接。

SKIPs 也可以被不同的 SKIP 取代 ，使得原始的 SKIP 过时。Replaced-By 和 Replaces 头部应分别添加到原始和新的 SKIPs 中。

Process SKIPs 如果从未打算完成，也可能具有 Active 状态，例如 SKIP 0（此 SKIP）。

SKIP 如何变为已接受#

一个 SKIP 由所有感兴趣的贡献者达成共识 Accepted 。我们需要一个具体的方法来判断是否已经达成共识。当你认为一个 SKIP 准备好接受时，在开发者论坛上发起一个主题，标题类似于：

接受 SKIP #<number>: <title> 的提案

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

链接到 SKIP 的最新版本，
简要描述任何主要的争议点以及它们是如何解决的，
包含一句话：“如果在本邮件发出后的7天内没有实质性的反对意见，那么SKIP将被接受；更多详情请参见SKIP 0。”

有关 NumPy 库中的等效示例，请参见：https://mail.python.org/pipermail/numpy-discussion/2018-June/078345.html

发送邮件后，你应该确保从 SKIP 的 讨论 部分链接到邮件线程，以便人们以后可以找到它。

通常，SKIP 作者将是发送此电子邮件的人，但任何人都可以这样做——重要的是确保每个人都知道 SKIP 即将被接受，并给他们最后一次回应的机会。如果有特殊原因需要将最终评论期延长至 7 天以上，那么也可以，只需在电子邮件中说明即可。你不应该少于 7 天，因为有时人们正在旅行或类似情况，需要一些时间来回应。

总的来说，目标是确保社区达成共识，而不是提供一个让人们试图钻空子的严格政策。如有疑问，倾向于寻求更多反馈并寻找妥协的机会。

如果在最终评论期内没有任何实质性反对意见，那么 SKIP 可以正式标记为 Accepted。你应该发送一封后续邮件通知列表（庆祝表情符号可选但鼓励 🎉✨），然后通过将其 :Status: 设置为 Accepted，并将其 :Resolution: 头设置为指向你的后续邮件的链接来更新 SKIP。

如果有*实质性*反对意见，那么 SKIP 仍将处于 草稿 状态，讨论将继续正常进行，一旦反对意见得到解决，可以再次提议接受。

在特殊情况下，当核心开发者之间无法达成共识时，可以请求 scikit-image 指导委员会来决定是否接受有争议的 SKIP。

维护#

一般来说，标准跟踪的 SKIP 在达到最终状态后不再修改，因为代码和项目文档被认为是已实现功能的最终参考。然而，在特殊情况下，它们可能会被更新。

随着时间的推移，Process SKIPs 可能会更新，以反映开发实践和其他细节的变化。在这些情况下，所遵循的确切流程将取决于所更新 SKIP 的性质和目的。

格式与模板#

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

标题前言#

每个 SKIP 必须以标题序言开头。标题必须按以下顺序出现。标有 * 的标题是可选的。所有其他标题都是必需的。:

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

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

随机 J. 用户 <address@dom.ain>

如果包含电子邮件地址，并且只是

随机 J. 用户

如果没有给出地址。如果有多个作者，每个作者应单独成行。