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 儲存庫發出提取請求，將其注入 scikit-image 開發工作流程。SKIP 越集中，越有可能被接受。

每個 SKIP 都必須有一位擁護者，即使用下方描述的樣式和格式撰寫 SKIP、在適當的論壇中引導討論，並嘗試圍繞該想法建立社群共識的人。SKIP 擁護者 (又名作者) 應首先嘗試確定該想法是否適合 SKIP。在 scikit-image 開發者論壇上發文是做到這一點的最佳方式。

提案應以草稿 SKIP 的形式，透過向 doc/source/skips 目錄發出 GitHub 提取請求來提交，名稱為 skip-<n>.rst，其中 <n> 是適當指定的數字 (例如，skip-35.rst)。草稿必須使用 SKIP X — 範本與說明檔案。

一旦 PR 建立完成，應在開發者論壇上宣布 SKIP 以進行討論 (PR 本身的評論應僅限於次要的編輯和技術修復)。

在盡早方便時，應合併 PR (無論其是否在討論期間被接受)。概述連貫論點且被認為合理完整的 SKIP 應樂觀地合併，無論其是否在討論期間被接受。作者可以建立其他 PR 來更新或擴展 SKIP，或者維護人員可以設定其狀態、討論 URL 等。

標準追蹤 SKIP 由兩部分組成，即設計文件和參考實作。一般建議至少與 SKIP 共同開發原型實作，因為原則上聽起來不錯的想法有時可能會被證明是不切實際的。通常，原型實作可作為對 scikit-image 儲存庫的 PR 提供，只要它被正確標記為 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 #<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

如果未提供地址。如果有多個作者，則每個作者都應該單獨一行。