貢獻 NumPy#

不是程式設計師？沒問題！NumPy 是多方面的，我們可以使用很多協助。以下是我們希望獲得協助的所有活動（它們都很重要，因此我們按字母順序排列）

  • 程式碼維護與開發

  • 社群協調

  • DevOps

  • 開發教育內容與敘事文件

  • 募款

  • 行銷

  • 專案管理

  • 翻譯內容

  • 網站設計與開發

  • 撰寫技術文件

我們理解每個人都有不同的經驗程度，而且 NumPy 是一個相當成熟的專案，因此很難對理想的「首次貢獻者」做出假設。因此，這就是為什麼我們不將 issue 標記為「good-first-issue」標籤的原因。相反地，您會找到標記為「Sprintable」的 issue。這些 issue 可以是

  • 容易修復，當您獲得經驗豐富的貢獻者的指導時（非常適合在衝刺 (sprint) 中工作）。

  • 對於那些準備好深入研究的人來說，一個學習機會，即使您不在衝刺 (sprint) 中。

此外，根據您先前的經驗，某些「Sprintable」issue 可能很容易，而另一些對您來說可能更具挑戰性。

本文檔的其餘部分討論了在 NumPy 程式碼庫和文件上工作。我們正在更新我們對其他活動和角色的描述。如果您對這些其他活動感興趣，請聯絡我們！您可以透過numpy-discussion 郵件列表或在 GitHub 上執行此操作（開啟一個 issue 或在相關 issue 上評論）。這些是我們首選的溝通管道（開源本質上是開放的！），但是，如果您希望先在更私密的空間中討論，您可以在 Slack 上進行（有關詳細資訊，請參閱 numpy.org/contribute）。

開發流程 - 摘要#

這是簡短摘要，完整的 TOC 連結如下

  1. 如果您是首次貢獻者

    • 前往 numpy/numpy 並點擊「fork」按鈕以建立您自己的專案副本。

    • 將專案複製到您的本機電腦

      git clone --recurse-submodules https://github.com/your-username/numpy.git

    • 變更目錄

      cd numpy

    • 新增上游儲存庫

      git remote add upstream https://github.com/numpy/numpy.git

    • 現在，git remote -v 將顯示兩個名為 remote 儲存庫

      • upstream，它指向 numpy 儲存庫

      • origin，它指向您的個人 fork

    • 從 upstream 拉取最新的變更，包括標籤

      git checkout main
git pull upstream main --tags

    • 初始化 numpy 的子模組

      git submodule update --init

  2. 開發您的貢獻

    • 為您要處理的功能建立一個分支。由於分支名稱將出現在合併訊息中，請使用一個合理的名稱，例如 'linspace-speedups'

      git checkout -b linspace-speedups

    • 在您進行時在本機提交（git add 和 git commit）使用正確格式化的提交訊息，編寫在您的變更之前失敗並在之後通過的測試，執行所有本機測試。請務必在 docstring 中記錄任何已變更的行為，並遵守 NumPy docstring 標準。

  3. 提交您的貢獻

    • 將您的變更推送回您在 GitHub 上的 fork

      git push origin linspace-speedups

    • 前往 GitHub。新的分支將顯示一個綠色的「Pull Request」按鈕。確保標題和訊息清晰、簡潔且不言自明。然後點擊按鈕提交。

    • 如果您的提交引入了新功能或變更了功能，請在郵件列表上發文以解釋您的變更。對於錯誤修復、文件更新等，通常不需要這樣做，但如果您沒有收到任何回應，請隨時要求審閱。

  4. 審閱流程

    • 審閱者（其他開發人員和感興趣的社群成員）將在您的 Pull Request (PR) 上撰寫 inline 和/或一般評論，以協助您改進其實作、文件和風格。每個參與專案的開發人員的程式碼都經過審閱，我們已將其視為友好的對話，我們都從中學習，並且整體程式碼品質受益。因此，請不要讓審閱讓您氣餒而停止貢獻：其唯一目的是提高專案的品質，而不是批評（畢竟，我們非常感謝您捐贈的時間！）。有關更多資訊，請參閱我們的審閱者指南。

    • 要更新您的 PR，請在您的本機儲存庫上進行變更、提交、執行測試，並且只有在它們成功時才推送至您的 fork。一旦這些變更被推送上去（到與之前相同的分支），PR 將自動更新。如果您不知道如何修復測試失敗，您可以推送您的變更，並在 PR 評論中尋求協助。

    • 各種持續整合 (CI) 服務會在每次 PR 更新後觸發，以建置程式碼、執行單元測試、測量程式碼覆蓋率並檢查您的分支的程式碼風格。CI 測試必須通過，您的 PR 才能合併。如果 CI 失敗，您可以透過點擊「failed」圖示（紅色十字）並檢查建置和測試日誌來找出原因。為了避免過度使用和浪費此資源，請在提交之前在本機測試您的工作。

    • PR 必須先獲得至少一位核心團隊成員的核准才能合併。核准表示核心團隊成員已仔細審閱變更，並且 PR 已準備好合併。

  5. 文件變更

    除了變更函式的 docstring 和一般文件中的可能描述之外，如果您的變更引入了任何面向使用者的修改，則可能需要在發行說明中提及它們。要將您的變更新增至發行說明，您需要建立一個包含摘要的簡短檔案，並將其放置在 doc/release/upcoming_changes 中。doc/release/upcoming_changes/README.rst 檔案詳細說明了格式和檔案命名慣例。

    如果您的變更引入了棄用，請務必先在 GitHub 或郵件列表上討論此事。如果就棄用達成協議，請遵循 NEP 23 棄用政策 以新增棄用。

  6. 交叉引用 issue

    如果 PR 與任何 issue 相關，您可以新增文字 xref gh-xxxx，其中 xxxx 是 issue 的編號到 github 評論中。同樣地，如果 PR 解決了一個 issue，請將 xref 替換為 closes、fixes 或任何其他 github 接受的風格。

    在原始碼中，請務必在任何 issue 或 PR 參考前面加上 gh-xxxx。

如需更詳細的討論，請繼續閱讀並追蹤此頁面底部的連結。

指南#

  • 所有程式碼都應具有測試（有關更多詳細資訊，請參閱下方的測試覆蓋率）。

  • 所有程式碼都應記錄文件。

  • 未經核心團隊成員的審閱和核准，絕不會提交任何變更。如果您在一週內沒有收到對您的 pull request 的任何回應，請在 PR 或郵件列表上禮貌地詢問。

風格指南#

  • 設定您的編輯器以遵循 PEP 8（移除尾隨空白、沒有 tab 等）。使用 pyflakes / flake8 檢查程式碼。

  • 使用 NumPy 資料類型而不是字串（np.uint8 而不是 "uint8"）。

  • 使用以下匯入慣例

    import numpy as np

  • 對於 C 程式碼，請參閱 NEP 45。

測試覆蓋率#

修改程式碼的 Pull request (PR) 應具有新的測試，或修改現有測試以使其在 PR 之前失敗，之後通過。您應該在推送 PR 之前執行測試。

在本機執行 NumPy 的測試套件需要一些額外的套件，例如 pytest 和 hypothesis。其他測試相依性列在頂層目錄的 requirements/test_requirements.txt 中，並且可以使用以下命令方便地安裝

$ python -m pip install -r requirements/test_requirements.txt

模組的測試應理想地涵蓋該模組中的所有程式碼，即語句覆蓋率應為 100%。

要測量測試覆蓋率，請執行

$ spin test --coverage

這將在 build/coverage 以 html 格式建立報告，可以使用您的瀏覽器查看，例如

$ firefox build/coverage/index.html

建置文件#

要建置 HTML 文件，請使用

spin docs

您也可以從 doc 目錄執行 make。make help 列出所有目標。

要取得適當的相依性和其他需求，請參閱建置 NumPy API 與參考文件。

開發流程 - 詳細資訊#

故事的其餘部分

NumPy 特定工作流程在 numpy-development-workflow 中。