SKIP 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（scikit-image 建议）。SKIP 是一份设计文档，为社区提供信息，或描述 scikit-image 或其流程或环境的新功能。如果适用，SKIP 应提供所提议更改的理由以及简洁的技术规范。

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

由于 SKIP 作为版本化存储库中的文本文件维护，因此其修订历史是功能建议的历史记录 [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 拉取请求提交到 doc/source/skips 目录，名称为 skip-<n>.rst，其中 <n> 是适当分配的数字（例如，skip-35.rst）。草案必须使用 SKIP X — 模板和说明文件。

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

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

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

审查和决议#

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

所有 SKIP 都应以 草稿 状态创建。

最终，经过讨论，可能会达成共识，即应接受 SKIP——有关详细信息，请参阅下一节。此时状态变为 已接受。

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

为了在承诺语言功能或标准库 API 的长期稳定性之前收集额外的设计和接口反馈，SKIP 也可以标记为“临时”。这是“临时接受”的简称，表示该提案已被接受纳入参考实现，但在最终确定完整设计之前需要额外的用户反馈。与常规接受的 SKIP 不同，临时接受的 SKIP 即使在相关更改已包含在某个版本中后，也可能仍会被拒绝或撤回。

在任何可能的情况下，都认为最好缩小提案的范围，以避免需要依赖“临时”状态（例如，通过将某些功能推迟到以后的 SKIP 中），因为此状态会导致更广泛的生态系统中出现版本兼容性问题。

SKIP 还可以分配状态 延迟。SKIP 作者或核心开发者可以在 SKIP 没有取得进展时为 SKIP 分配此状态。

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

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

SKIP 也可以被另一个 SKIP 取代，使原始 SKIP 过时。被取代 和 取代 标题应分别添加到原始和新的 SKIP 中。

如果流程 SKIP 从未打算完成，例如 SKIP 0（此 SKIP），则流程 SKIP 也可以具有 活跃 状态。

SKIP 如何被接受#

SKIP 由所有感兴趣的贡献者达成共识而 接受。我们需要一种具体的方法来判断是否已达成共识。当您认为 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。您应该发送一封后续电子邮件通知列表（可选但鼓励使用庆祝表情 🎉✨），然后更新 SKIP，将其 :Status: 设置为 Accepted，并将 :Resolution: 标头设置为指向后续电子邮件的链接。

如果存在实质性异议，则 SKIP 保持在 Draft 状态，讨论照常继续，并且可以在稍后解决异议后再次提议接受。

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

维护#

通常，标准跟踪 SKIP 在达到最终状态后不再修改，因为代码和项目文档被视为已实现功能的最终参考。但是，它们可能会在特殊情况下进行更新。

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

格式和模板#

SKIP 是使用 reStructuredText 格式的 UTF-8 编码文本文件。请参阅 SKIP X — 模板和说明文件和 reStructuredTextPrimer 以获取更多信息。我们使用 Sphinx 将 SKIP 转换为 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>

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

Random J. User <address@dom.ain>

如果包含电子邮件地址，则只需

Random J. User

如果不提供地址。如果有多个作者，则每个作者应位于单独一行。