審閱者指南#

審閱開放的提取請求 (PR) 有助於推動專案向前發展。我們鼓勵專案外部的人員也參與其中；這是熟悉程式碼庫的好方法。

誰可以成為審閱者？#

審閱可以來自 NumPy 團隊外部 – 我們歡迎來自領域專家（例如，linalg 或 fft）或其他專案維護者的貢獻。您不需要成為 NumPy 維護者（具有合併 PR 權限的 NumPy 團隊成員）才能進行審閱。

如果我們還不認識您，請考慮在您開始審閱提取請求之前，先在郵件列表或 Slack 中自我介紹。

溝通指南#

  • 每個 PR，無論好壞，都是一種慷慨的行為。以正面的評論開頭將有助於作者感到受到肯定，並且您後續的意見可能會被更清楚地聽到。您也可能會感覺良好。

  • 如果可能，請從較大的問題開始，以便作者知道他們已被理解。抵制立即逐行查看，或以小的普遍性問題開頭的誘惑。

  • 您是專案的門面，而 NumPy 在不久前決定了它將成為哪種專案：開放、有同理心、歡迎、友善和耐心。請友善對待貢獻者。

  • 不要讓完美成為好的敵人，尤其是對於文件。如果您發現自己提出了許多小的建議，或對風格或語法過於吹毛求疵，請考慮在所有重要問題都得到解決後合併當前的 PR。然後，直接推送提交（如果您是維護者）或自己開啟後續的 PR。

  • 如果您在撰寫審閱回覆時需要幫助，請查看一些審閱的標準回覆。

審閱者檢查清單#

  • 在所有情況下，預期的行為是否清晰？ 一些需要注意的事項

    • 對於意外的輸入，例如空陣列或 nan/inf 值，會發生什麼情況？

    • 是否有測試軸或形狀參數為 int 或 tuples？

    • 如果函數支援，是否有測試不尋常的 dtypes？

  • 變數名稱是否應改進以提高清晰度或一致性？

  • 是否應添加註解，還是應刪除不 helpful 或不必要的註解？

  • 文件是否遵循 NumPy 指南？ 文件字串的格式是否正確？

  • 程式碼是否遵循 NumPy 的 風格指南？

  • 如果您是維護者，並且從 PR 描述中不明顯，請在合併訊息中簡短說明分支做了什麼，如果關閉 issue，也請添加「Closes gh-123」，其中 123 是 issue 編號。

  • 對於程式碼變更，至少一位維護者（即具有提交權限的人）應審閱並批准提取請求。如果您是第一個審閱 PR 並批准變更的人，請使用 GitHub 批准審閱 工具將其標記為已批准。如果 PR 很簡單，例如，它是一個明顯正確的錯誤修復，則可以立即合併。如果它更複雜或變更了公共 API，請讓它保持開放至少幾天，以便其他維護者有機會審閱。

  • 如果您是已批准 PR 的後續審閱者，請使用與新 PR 相同的審閱方法（專注於較大的問題，抵制只添加一些小問題的誘惑）。如果您有提交權限，並且認為不再需要審閱，請合併 PR。

給維護者#

  • 在合併 PR 之前，請確保所有自動化 CI 測試都通過，並且文件建置沒有任何錯誤。

  • 如果發生合併衝突，請要求 PR 提交者基於 main 分支重新變基。

  • 對於添加新功能或在某些方面很複雜的 PR，請等待至少一兩天再合併它。這樣，其他人就有機會在程式碼進入之前發表評論。考慮將其添加到發行說明中。

  • 在合併貢獻時，提交者有責任確保這些貢獻符合 NumPy 開發流程指南 中概述的要求。此外，請檢查新功能和向後相容性中斷是否已在 numpy-discussion 郵件列表中討論過。

  • 如果您認為 PR 過於混亂，可以壓縮提交或清理提交訊息。請記住在執行此操作時保留原始作者的姓名。確保提交訊息遵循 NumPy 的規則。

  • 當您想要拒絕 PR 時：如果它非常明顯，您可以直接關閉它並解釋原因。如果不明顯，那麼最好先解釋您為什麼認為 PR 不適合包含在 NumPy 中，然後讓第二位提交者評論或關閉。

  • 如果 PR 提交者在 6 個月內沒有回覆您的評論，請將有問題的 PR 移動到非活動類別，並附上「inactive」標籤。此時，維護者可以關閉 PR。如果對完成正在考慮的 PR 有任何興趣，可以隨時透過評論表明，無需等待 6 個月。

  • 鼓勵維護者在合併之前僅需進行少量變更時（例如，修復程式碼風格或語法錯誤）完成 PR。如果 PR 變得不活動，維護者可能會進行較大的變更。請記住，PR 是貢獻者和審閱者之間的協作，有時直接推送是完成它的最佳方式。

API 變更#

如前所述，大多數公共 API 變更都應提前討論，並且通常與更廣泛的受眾（在郵件列表上，甚至透過 NEP）討論。

對於公共 C-API 中的變更，請注意 NumPy C-API 是向後相容的，因此任何新增內容都必須與以前的版本 ABI 相容。如果不是這種情況，您必須添加 guard。

例如，PyUnicodeScalarObject 結構包含以下內容

#if NPY_FEATURE_VERSION >= NPY_1_20_API_VERSION
    char *buffer_fmt;
#endif

因為 buffer_fmt 欄位已在 NumPy 1.20 中添加到其末尾（所有先前的欄位都保持 ABI 相容）。同樣地，在 numpy/_core/code_generators/numpy_api.py 中的 API 表中添加的任何函數都必須使用 MinVersion 註解。例如

'PyDataMem_SetHandler':                 (304, MinVersion("1.22")),

僅標頭功能（例如，新的巨集）通常不需要 guard。

GitHub 工作流程#

在審閱提取請求時，請適當地使用 GitHub 上的工作流程追蹤功能

  • 在您完成審閱後，如果您想要求提交者進行變更，請將您的審閱狀態變更為「需要變更」。這可以在 GitHub、PR 頁面、「Files changed」標籤頁、「Review changes」（右上角的按鈕）上完成。

  • 如果您對目前的狀態感到滿意，請將提取請求標記為「已批准」（與「需要變更」相同的方式）。或者（對於維護者）：如果您認為提取請求已準備好合併，請合併它。

在您自己的機器上檢查提取請求程式碼的副本可能會很有幫助，這樣您就可以在本地使用它。您可以透過點擊 PR 頁面右上角的 Open with 按鈕，使用 GitHub CLI 來執行此操作。

假設您已設定 開發環境，您現在可以建置程式碼並進行測試。

審閱的標準回覆#

將其中一些儲存在 GitHub 的 已儲存回覆 中以供審閱可能會很有幫助

用法問題
You are asking a usage question. The issue tracker is for bugs and new features.
I'm going to close this issue, feel free to ask for help via our [help channels](https://numpy.dev.org.tw/gethelp/).
歡迎您更新文件
Please feel free to offer a pull request updating the documentation if you feel it could be improved.
錯誤的獨立範例
Please provide a [self-contained example code](https://stackoverflow.com/help/mcve), including imports and data (if possible), so that other contributors can just run it and reproduce your issue.
Ideally your example code should be minimal.
軟體版本
To help diagnose your issue, please paste the output of:
```
python -c 'import numpy; print(numpy.version.version)'
```
Thanks.
程式碼區塊
Readability can be greatly improved if you [format](https://help.github.com/articles/creating-and-highlighting-code-blocks/) your code snippets and complete error messages appropriately.
You can edit your issue descriptions and comments at any time to improve readability.
This helps maintainers a lot. Thanks!
連結到程式碼
For clarity's sake, you can link to code like [this](https://help.github.com/articles/creating-a-permanent-link-to-a-code-snippet/).
更好的描述和標題
Please make the title of the PR more descriptive.
The title will become the commit message when this is merged.
You should state what issue (or PR) it fixes/resolves in the description using the syntax described [here](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword).
需要回歸測試
Please add a [non-regression test](https://en.wikipedia.org/wiki/Non-regression_testing) that would fail at main but pass in this PR.
不要變更不相關的內容
Please do not change unrelated lines. It makes your contribution harder to review and may introduce merge conflicts to other pull requests.