跳到主要內容

指南

轉移到 conda-forge​

本文件旨在闡述一些關於將 conda-recipes 和 anaconda-recipes 轉移到 conda-forge 的指導原則。這些並非硬性規定，而是開放給合理的解釋和審閱者的判斷。

預計幾乎所有來自這些儲存庫的 recipe 都將被提議添加到這裡，儘管可能會決定少數 recipe 實際上不屬於這裡，或者不應該再被支援。

在從任一位置新增套件時，請檢查提交歷史以查看過去誰對 recipe 進行了變更。任何接觸過該 recipe 的人都應該被提及，以便他們可以被新增到這裡。如果 recipe 在新增之前需要任何調整，也應該諮詢他們的意見。此外，應該詢問他們是否願意被新增為維護者。只有在他們同意擔任維護者角色的情況下，才應該將他們新增到維護者列表中。

在移植 recipe 的所有情況下，您都應該將自己新增為維護者。這些儲存庫的一些貢獻者可能非常多產，但可能沒有那麼積極參與。如果他們指定只希望針對某些 recipe 或完全不希望被打擾，請尊重他們的意願並也將他們新增進來。記下他們希望收到通知的 recipe（如果有的話）。如果他們不再對任何 conda recipe 感興趣，也在此處記錄下來。在聯繫任何人之前，請查閱此 issue 中的列表，以查看該貢獻者是否有任何限制。

在移植時，請確保 recipe 遵循程式碼風格規範。區塊順序應為 package、source、build、requirements、test、about、extra/recipe-maintainers。建議新增一個 build 區塊，並將 number 明確設定為 0，即使其餘部分是不需要的。如果沒有 Windows 的 build，請確保在 build 區塊中新增 skip: true # [win]。about 區塊必須包含 home URL（驗證 URL 是否仍然正確）、license（驗證是否存在正確的許可證）以及一句話（或幾個字）的 summary。在指定版本時，強烈建議使用 Jinja 模板來在頂部設定版本（例如 {% set version = "0.10.1" %}），然後將所有版本的使用位置替換為 {{ version }}。應優先選擇壓縮原始碼包而不是版本控制簽出。確保所有壓縮原始碼包的連結都允許輕鬆更改版本（使用 latest 是不可接受的）。此外，所有壓縮原始碼包都應包含檢查碼，以便驗證下載。

所有套件都必須新增測試。這些測試可以包括但不限於：檢查是否已安裝函式庫、Python 導入、簡單的程式碼片段以編譯或執行基本測試、命令列用法（檢查說明或版本）。建議讓編譯後的程式碼執行所有測試（例如 make check），以確保其已正確建置。這通常應該在 build 中發生。

雖然不建議，但可以將多個 recipe 包含在 staged-recipes 的單個 Pull Request 中。conda-build-all 用於確定 build 順序和必要的 build 矩陣（例如，針對哪些 Python 版本進行 build）。從實務角度來看，持續整合資源和審閱者在單個 Pull Request 中能夠/願意審閱的內容都存在限制。包含大量 recipe 的大型 Pull Request 會使審閱更加困難。如果這些 recipe 通過了這兩個限制並被合併，則不同 feedstock 之間的競爭條件可能需要您和/或核心維護者重新啟動它們，以適當的順序建置所有內容。這並不是說不能在單個 Pull Request 中新增多個 recipe。當然可以這樣做，並且可以運作，但建議是首先開啟一個包含一個 recipe 的 PR，然後提及 @conda-forge/core 以徵求關於新增一兩個額外 recipe 的同意。

預期用途​

維護者的時間和 CI 資源是 conda-forge 能夠運作的基礎。它們與其價值一樣稀缺。conda-forge 有足夠的能力支援發布套件，但沒有能力開發套件。

將套件發布到 conda-forge 表示它適合不參與開發的使用者。但是，發布並非總是無錯誤的。在除錯發布過程本身的問題時，多次提交是可以接受的。

幸運的是，有一些選項可以最佳化套件的開發。

  • conda-smithy 是 conda-forge 本身用於管理 feedstock 的工具。conda-smithy 可用於建立與 conda-forge 分開的內部開發 feedstock。
  • ci-helpers 是一組使用環境變數驅動各種 CI 服務的腳本。

重新命名套件​

有時，套件會被錯誤命名。要更正套件的名稱，請向 staged-recipes 提交一個包含正確名稱的 PR。在審閱過程中，請務必註明套件已重新命名，並聯繫 conda-forge/core 的成員以移除舊的 feedstock（以及可能需要的套件）。

有時，需要更新 feedstocks 中的 .gitmodules 檔案，以移除舊的 feedstock。尚不完全清楚這些情況是什麼。請參閱 conda-forge.github.io#1070。

如果現有的 feedstock 已經建立了一個同名的套件，那麼您可能需要將新的 feedstock 新增到 feedstock-outputs 對應表中。

修復損壞的套件​

有時，您需要從 Anaconda.org 上的 conda-forge 頻道中移除套件。原因可能有很多，但立即想到的有：

  • 不正確的釘選或元數據
  • 套件被重新命名
  • 套件內容損壞

我們傾向於不因以下原因移除套件：

  1. 未受影響的使用者無法取得損壞的套件。
  2. 無法還原（如果我們錯誤地移除了它怎麼辦）。
  3. 失去可重現性（無法建立舊的環境）。
  4. 不夠社群友善（沒有留下審閱決策的機會）。
  5. 阻止任何人檢查損壞的套件。

相反地，如果可能，我們傾向於採取以下措施之一：

  1. 如果唯一的問題在於套件元數據，我們可以透過 repo data patches feedstock 直接修補它。要更改套件的 repo data，請在 feedstock 上建立 PR。
  2. 如果套件內容本身已損壞，我們會在套件中新增一個額外的標籤 broken。帶有此額外標籤的套件將從 main 標籤的 repo data 中移除。因此，它們不會被解算器考慮，但它們的二進制檔案仍然可以在 Anaconda.org 上取得。要將 broken 標籤新增到您的套件，請參閱移除損壞的套件。

將 broken 標籤新增到套件比修補 repo data 更具破壞性，因此我們更傾向於使用 repo data patches 而不是將事物標記為 broken。

成為維護者​

conda-forge 是一個社群專案，因此可能會發生 feedstock 暫時被棄置的情況。您可以透過將您的 github-id 新增到 recipe 的 meta.yaml 中的 recipe-maintainers 區塊，來加入 feedstock 的維護者團隊。請參閱 更新維護者列表 以取得詳細說明。

語言版本​

conda-forge 包含來自多種語言的套件，包括 Python 和 R 等等。這些特定於語言的套件管理子生態系統中的每一個都需要跟上語言本身的節奏，這使得為舊版本的語言保留多長時間制定一個全面的政策變得具有挑戰性。當問題出現時，每個群組都應該能夠定義自己關於舊版本的語言保留多長時間的政策。

Python​

對於 Python 語言，conda-forge 的目標是保持套件建置的活躍性和可用性，以支援當前版本和至少前兩個次要版本。每當 Python 4.0 出現時，我們都需要弄清楚這個政策是否應該更改為同時支援多個版本的 3.x 和 4.x。幸運的是，我們現在可以暫緩處理這個問題。何時決定放棄舊語言版本的問題仍然存在。我們在此可以提供的指導有兩方面：

  1. 我們將與社群一同前進。當我們的核心函式庫停止支援舊版本時，conda-forge 也將如此。我們在決定放棄舊版本時考慮的（非詳盡）核心函式庫列表如下：
    • matplotlib
    • numpy
    • scipy
    • pypy
  2. 核心團隊可以決定暫時保留舊版本，直到滿足某些特定標準。例如，我們暫緩關閉 py36，直到 pypy 推出 pypy3.7。
  3. 如果社群中有很多人依賴舊版本，核心團隊可以決定保留舊版本。例如，即使 numpy、scipy 放棄了支援，我們也暫緩關閉 py27，因為社群中有許多人有興趣保持支援直到該版本的生命週期結束。

審閱 recipe​

要將新套件新增到 conda-forge，使用者可以向 staged-recipes 提交 PR（詳情請參閱 貢獻套件），它將經過一系列自動檢查和程式碼審閱。任何 conda-forge 成員都可以執行程式碼審閱，但最終合併只能由 staged-recipes 或 core 團隊完成。以下章節建議如何執行成功的程式碼審閱的指南。我們將「必要」和「建議」區分如下：

  • 必要：這些指南非常重要，是 PR 接受的必要條件。例外情況很少見，通常需要 core 批准。
  • 建議：這些被認為是「錦上添花」的功能。理想情況下，所有 recipe 都應該遵守它們，但只要提供合理的理由，就可以容忍例外情況。

通用原則​

必要

  1. 審閱中的所有互動都遵守我們的行為準則。
  2. conda-forge-linter 檢查 成功通過。有時，linter 也會建議被認為是可選的修改（提示）；即使是建議的，這些也不是接受提交的必要條件。
  3. CI 檢查在必要的平台上成功通過。例外情況：
    • noarch: python 可能在 Linux 以外的平台（例如，缺少依賴項）上失敗。對於非 noarch 套件，應透過 skip: true # [<平台選擇器>] 跳過失敗的平台
    • CI 超時或儲存空間不足，因為它嘗試在同一個工作中建置所有 Python 版本。只要一個版本通過，就可以了，因為它們將在結果 feedstock 中單獨運行。
  4. 提交符合 Pull Request 模板檢查清單。
  5. 許可證已正確識別並允許重新發布。
  6. 原始碼不應包含捆綁程式碼。如果包含：
    • 將捆綁專案單獨打包，並在 requirements 區塊中指定所需的依賴項。如果運行時需要捆綁程式碼，則為首選。
    • 允許捆綁程式碼，但請確保許可證檔案包含在 about.license 欄位中。如果僅是建置時的依賴項（例如，僅標頭檔的函式庫），通常可以接受

建議

  1. 原始碼應從提供穩定 tarball 的 URL 取得（一段時間內 SHA 相同）。Git 或其他 SVC 儲存庫應僅作為最後手段使用。
  2. 包含在 conda-forge 釘選 中的 Host 依賴項應為僅限名稱；即它們不指定單獨的版本。
  3. 運行時依賴項的釘選不應過於嚴格，除非有正當理由。感謝 repo data patches，我們可以對下限或上限保持樂觀，而不是單一版本釘選：>=1.4.2,<1.5 優於 ==1.4.2。
  4. 套件應將其檔案放置在標準位置下（例如，$PREFIX/bin 下的可執行檔），除非提供合理的理由。

Python 相關細節​

必要

  1. noarch: python 套件符合被視為此類套件的必要標準。

建議

  1. 套件不會意外包含 tests（也包括 test、_tests 或類似名稱）頂層套件。檔案列表通常在 pip install 在 adding license file 訊息之後印出。如果發生這種情況，上游應相應地修改其 setuptools.find_packages() 用法。或者，可以應用補丁。請參閱範例。
  2. test.imports 檢查的模組不是空的（這可能會發生在頂層套件中的佔位符 __init__.py 檔案中）。
  3. pip list 和 conda build 日誌報告的版本匹配。
  4. pip check 通過。請參閱 pip check 以取得更多詳細資訊。
  5. 如果專案可以被視為 noarch（請參閱標準），則應將其打包為此類套件。

編譯後的物件​

必要

  1. 原始碼不包含編譯後的文件。原則上，所有編譯後的物件都需要在 CI 中從原始碼生成。此規則的例外情況（例如，二進制重新封裝）需要明確批准。

建議

  1. SONAME 遵循上游給出的命名建議。
  2. 如果 ABI 兼容性對於套件很重要，則應相應地設定 run_exports。請參閱 釘選的依賴項 和 conda-build 文件 以取得更多資訊。