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 开发者论坛上发帖是执行此操作的最佳方法。

提案应通过向 doc/source/skips 目录发出 GitHub 拉取请求来以草案 SKIP 的形式提交，名称为 skip-<n>.rst，其中 <n> 是适当分配的数字（例如，skip-35.rst）。草案必须使用 SKIP X — 模板和说明文件。

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

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

标准跟踪 SKIP 由两个部分组成：设计文档和参考实现。通常建议至少与 SKIP 共同开发一个原型实现，因为原则上听起来不错的想法有时会被发现是不切实际的。通常，将原型实现作为 PR 提供给 scikit-image repo 是有意义的，只要它被正确标记为 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 永远不会完成，例如 SKIP 0（此 SKIP），则它们也可能具有 活跃 状态。

SKIP 如何被接受#

SKIP 由所有感兴趣的贡献者达成共识 已接受。我们需要一种具体的方法来判断是否已达成共识。当您认为 SKIP 已准备好接受时，请在开发者论坛上发起一个主题，主题如下所示

接受 SKIP #<编号> 的提案：<标题>

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

链接到 SKIP 的最新版本，
简要描述任何主要争议点以及它们是如何解决的，
包含类似这样的句子：“如果自此邮件发出后7天内没有实质性反对意见，则该SKIP将被接受；详情请参阅SKIP 0。”

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

发送电子邮件后，您应该确保将电子邮件线程链接到 SKIP 的 Discussion 部分，以便人们稍后可以找到它。

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

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

如果最终评论期在没有任何实质性反对意见的情况下结束，则可以正式将 SKIP 标记为 Accepted。您应该发送一封后续电子邮件通知列表（可以添加庆祝表情符号 🎉✨，但不强制），然后通过将其 :Status: 设置为 Accepted，并将其 :Resolution: 标头设置为指向您的后续电子邮件的链接来更新 SKIP。

如果有实质性反对意见，则 SKIP 保持 Draft 状态，讨论照常继续，并且可以在解决反对意见后再次提出接受建议。

在不寻常的情况下，如果核心开发人员之间无法达成共识，则可以请求 scikit-image 指导委员会决定有争议的 SKIP 是否 Accepted。

维护#

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

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

格式和模板#

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

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