核心開發者指南#

歡迎，新的核心開發者！核心團隊感謝您工作的品質，並樂於與您合作；因此，我們邀請您加入我們。感謝您至今對專案的眾多貢獻。

本文檔提供您新角色的指導方針。首先，您應該熟悉專案的使命、願景和價值觀。如有疑問，請務必參考此處。

作為核心團隊成員，您有責任引導其他貢獻者完成審查流程；以下是一些指導方針。

所有貢獻者都受到相同的待遇#

您現在可以直接將變更推送到主分支，但不應這樣做；相反，請像以前一樣，並根據一般貢獻者指南，繼續提出 pull request。

作為核心貢獻者，您可以合併或批准其他貢獻者的 pull request。就像核彈發射鑰匙一樣，這是一種共享的權力：您必須在其他核心成員批准 pull request 且在您自己仔細審查過後，才能合併。（請參閱下面的審查，尤其是僅合併您了解的變更。）為確保乾淨的 git 歷史記錄，請使用 GitHub 的Squash and Merge 功能進行合併，除非您有充分的理由不這樣做。

審查#

如何進行良好的審查#

始終善待貢獻者。幾乎所有 scikit-image 都是志願工作，我們對此非常感激。對想法和實作提供建設性的批評，並提醒自己，當您的作品作為新手被評估時的感受。

scikit-image 非常重視程式碼審查中的指導。新使用者通常需要更多的協助，因為他們幾乎沒有 git 經驗。請重複說明，如果您不認識某位貢獻者，請將他們指向我們的開發指南，或網路上其他 GitHub 工作流程教學。不要假設他們知道 GitHub 的運作方式（例如，許多人沒有意識到新增 commit 會自動更新 pull request）。溫和、禮貌、友善的鼓勵可以決定一位新的核心開發者或一個被放棄的 pull request。

審查時，請專注於以下幾點

  1. API： API 是使用者首次使用 scikit-image 時看到的內容。API 一旦發佈就難以變更，因此應該簡單、函數式（即不攜帶狀態）、與程式庫的其他部分一致，並且應避免修改輸入變數。請熟悉專案的棄用政策

  2. 文件：任何新功能都應該有一個圖庫範例，不僅要說明還要解釋它。

  3. 演算法：在批准程式碼之前，您應該了解正在修改或新增的程式碼。（請參閱下面的僅合併您了解的變更。）實作應該按照它們所聲稱的那樣執行，並且應該簡單、可讀且高效。

  4. 測試：對程式庫的所有貢獻都必須經過測試，並且每新增一行程式碼都應至少有一個測試涵蓋。良好的測試不僅執行程式碼，還會探索邊緣情況。不審查測試是很誘人的，但請務必這樣做。

  5. 授權：新的貢獻應該以與scikit-image 的授權相同的授權或與之相容的授權提供。與 BSD 相容的授權範例有MIT 授權和Apache 授權 2.0。如有疑問，請向團隊尋求協助。如果您（貢獻者）不是提交程式碼的著作權持有人，請徵求原始作者的同意，並在 LICENSE.txt 中加入他們的名字。您可以使用該檔案中的其他條目作為範本。

  6. 既有方法：一般來說，我們希望包含既有、在文獻中有詳細記錄並廣泛用於影像社群的演算法和方法。雖然這不是硬性要求，但新的貢獻應與我們的使命保持一致。

其他變更可能是吹毛求疵：拼寫錯誤、格式設定等。不要要求貢獻者進行這些變更，而是透過推送到他們的分支或使用 GitHub 的建議功能 來進行變更。（後者是首選，因為它讓貢獻者可以選擇是否接受變更。）

我們的預設合併政策是將所有 PR commit 合併到單一 commit 中。希望將 main 中的最新變更帶入其分支的使用者應被建議合併，而不是 rebase。即使發生合併衝突，除非您知道貢獻者有 git 經驗，否則不要要求 rebase。相反，請自己 rebase 分支，強制推送到他們的分支，並告知貢獻者如何強制提取。如果貢獻者不再活躍，您可以透過提交新的 pull request 並關閉原始 pull request 來接管他們的分支。在這樣做時，請確保您傳達您不會拋棄貢獻者的工作！

在您推送新的變更後，請在 pull request 中新增註記；GitHub 不會發送這些變更的通知。

僅合併您了解的變更#

長期可維護性是一個重要的考量因素。程式碼不僅必須有效，而且應該讓多位核心開發人員了解。未來必須進行變更，而原始貢獻者可能已經離開。

因此，除非您了解程式碼變更，否則不要合併。請隨時尋求協助：我們長期以來一直諮詢社群成員，甚至外部開發人員，以便在需要時獲得額外的見解，並且將其視為絕佳的學習機會。

雖然我們共同「擁有」成為程式碼基礎一部分的任何補丁（和錯誤！），但您是為您合併的變更背書。請認真對待這項責任。

實際上，如果您是審查和批准指定 pull request 的第二位核心開發人員，您通常會在批准後合併它（再次使用 GitHub 的 Squash and Merge 功能）。此過程有哪些例外情況？如果 pull request 特別具有爭議性或引起很多辯論（例如，涉及 API 變更），那麼您可能需要等待幾天才能合併。這種等待時間讓其他人有機會在他們對 pull request 的目前狀態不滿意時提出意見。另一個特殊情況是，第一次批准審查發生在很久以前，並且在此期間發生了很多變更。

當壓縮 commit 時，GitHub 會串聯所有 commit 訊息。請編輯產生的訊息，使其能夠簡潔地概述變更。例如，您可能想要從 PR 本身擷取描述，並刪除諸如「pep8 fix」、「apply review comments」等行。請保留所有 Co-authored-by 條目。

關閉 issue 和 pull request#

有時，必須關閉未完全解決的 issue。這可能是因為以下幾個原因

  • 原始貼文背後的人沒有回覆澄清要求，並且沒有任何核心開發人員能夠重現他們的問題；

  • 解決此問題很困難，並且被認為使用案例太過小眾，無法投入持續的努力或將其優先於其他問題；或

  • 核心開發人員認為使用案例或功能要求不屬於 scikit-image，

等等。同樣地，有時需要關閉 pull request 而不合併，因為

  • 這個 Pull Request 實作了一個我們認為不值得增加維護負擔的小眾功能；

  • 這個 Pull Request 實作了一個有用的功能，但需要大量努力才能達到 scikit-image 的標準，而原始貢獻者已經離開，而且沒有其他開發者願意進行必要的變更；或者

  • 這個 Pull Request 進行的變更不符合我們的價值觀，例如為了實現微幅的加速而顯著增加函式的程式碼複雜度，

以及其他情況。

所有這些都可能是關閉的合理理由，但我們必須謹慎，不要在沒有解釋的情況下關閉 Issue 或 Pull Request 而疏遠貢獻者。在關閉時，您的訊息應

  • 清楚說明關閉的決策是如何做出的。當決策是在社群會議上做出的時，這一點尤其重要，因為社群會議不像 Issue 本身的評論串那樣有明顯的記錄；

  • 感謝貢獻者的工作；並且

  • 為貢獻者或任何其他人提供明確的途徑來對決策提出申訴。

這些重點有助於確保所有貢獻者都感到被歡迎，並有權繼續貢獻，無論過去的貢獻結果如何。

其他資源#

身為核心成員，您應該熟悉社群和開發人員的資源，例如

您不需要監控所有的社群資源。

邀請新的核心成員#

任何核心成員都可以提名其他貢獻者加入核心團隊。提名會在一個私人的電子郵件清單上進行，skimage-core@discuss.scientific-python.org。截至撰寫本文時，關於誰可以被提名沒有硬性規定；至少，他們應該：參與專案至少六個月、貢獻了重大的變更、參與了對他人工作的討論和審閱，並以符合我們社群價值觀的方式進行協作。

為本指南做出貢獻！#

本指南反映了目前核心開發人員的經驗。我們很可能遺漏了一些現在已經變得理所當然的事情，而您身為新的團隊成員，會更容易發現這些事情。如果您有任何疑問，請詢問其他核心開發人員，並提交一個包含您所獲得見解的 Pull Request。

結論#

我們很高興您加入我們！我們期待您對程式碼庫和社群的貢獻。預先感謝您！