參與貢獻¶

Pip 的內部運作¶

我們有關於 pip 內部架構的進行中指南。在你深入探討時，這可能會對你有所幫助。

提交 Pull Request¶

提交針對 main 分支的 Pull Request，提供關於你正在執行什麼以及為什麼的良好描述。你必須獲得合法許可才能散布你對 pip 做出的任何程式碼，且它必須能在 MIT 授權下取得。

提供涵蓋變更內容的測試，並先行在本地執行測試。pip 支援多個 Python 版本和作業系統。任何要 Pull Request 都必須考量並可在這些平台上執行。

Pull Request 應該較小，才能利於輕鬆審查。保持它們為獨立且範圍有限。研究顯示審查品質會隨補丁大小增加而下降。有時候這會導致許多小型 PR 才能達成一個大型功能。特別是，Pull Request 不應被視為「功能分支」，而是在 PR 內持續進行開發工作。反之，這個功能應分解為更小的獨立部分，可個別審查和合併。

此外，避免納入和變更無關的程式碼的「表面」變更，因為這些會讓審查 PR 更困難。範例包括重排註解或文件中的文字，或在行內新增或移除空白行或空白處。若需要，可以個別進行這類變更，做為一個「格式整理」的 PR。

自動化測試¶

所有針對「main」分支的 Pull Request 和合併都會使用基於我們的 .github/workflows 檔案的 GitHub Actions 進行測試。可在 CI 文件中找到 pip 持續整合的更多資訊。

你可以在 GitHub 的 Pull Request 網頁使用者介面上找到針對你的 PR 的 CI 執行狀態和結果。如果 CI 執行失敗而你想要檢視輸出，你也可以在「詳細資料」連結中找到連結至特定建置的 CI 服務頁面。

若要觸發 CI 再次執行某個 Pull Request，你可以關閉並開啟 Pull Request，或提交另一個變更至 Pull Request。如果需要，專案維護人員可以手動觸發工作/建置的重新啟動。

要了解 pip 中依賴解析的更廣泛軟體架構，以及我們如何自動化測試這個功能，請參閱測試下一代 pip 依賴解析器。

新聞條目¶

使用 towncrier 管理 NEWS.rst 檔案，所有非瑣碎的變更都必須搭配新聞條目。

若要將條目新增至新聞檔案，您必須先建立問題描述您要進行的變更。拉取請求本身可以用作問題描述，但建議建立專屬的問題（例如，如果由於程式碼品質原因而導致 PR 遭拒）。

有了問題或拉取請求之後，請取得編號，並在 news/ 目錄中建立一個檔案，檔案名稱必須和問題編號相同，並加上「類型」，例如 removal、feature、bugfix 或 doc。

如果問題或 PR 編號是 1234，而且這項變更修正了錯誤，因此您將建立一個檔案 news/1234.bugfix.rst。PR 可以透過建立多個檔案來跨越多個類別（例如，如果您同時新增功能與將舊功能標示為不建議使用/移除，則您會建立 news/NNNN.feature.rst 和 news/NNNN.removal.rst）。

如果 PR 涉及多個問題/PR，您可以為每個問題/PR 建立一個檔案，內容完全相同，而 Towncrier 會自動移除重複資料。

新聞條目內容¶

此檔案的內容是 reStructuredText 格式的文字，將做為新聞檔案條目的內容。您不需在條目中參考問題或 PR 編號，因為在呈現 NEWS 檔案時，towncrier 會自動加入所有受影響問題的參考。檔案結尾必須換行。

為了在 NEWS.rst 檔案中維持一致的風格，新聞條目建議簡潔扼要、以句子形式呈現、長度小於 80 個字元且語氣肯定，也就是說，條目必須能用於完成句子「這項變更將會…」。在極少數的情況下，如果一行長度不夠，請使用肯定語氣的摘要行，之後換行，並將其與特點/變更說明（一或多個段落）分開，每個段落換行位置為 80 個字元。請記住，新聞條目是提供給最終使用者的，因此僅應包含與最終使用者相關的詳細資料。

選擇新聞條目類型¶

任何不會保證可在新聞檔案中輸入的項目均為瑣碎變更。以下列舉一些範例：就公眾而言，並無變動的程式碼重構、拼字修正、空白修改等。若要標記公關為瑣碎，只需要參與者將隨機命名的空檔案新增至 news/ 目錄，副檔名為 .trivial.rst。如果您在類似POSIX的作業系統上，可以執行 touch news/$(uuidgen).trivial.rst 新增檔案。在 Windows 上，可以使用 New-Item "news/$([guid]::NewGuid()).trivial.rst" 在 Powershell 中獲得相同的結果。核心提交者也可以為公關新增「略過新聞」標籤，結果將相同。

使用 news/<library>.vendor.rst 檔案升級、移除或新增新的供應商程式庫會獲得特別的提及。除了拉入此程式庫所帶來的任何功能、錯誤修正或其他類型的新聞之外，此檔案還會另行提及。此檔案以程式庫名稱作為金鑰，以便更新同一個程式庫兩次時，不會產生兩則新聞檔案輸入項。

使用 news/<name>.process.rst 檔案，可以變更程序、政策或其他非程式碼相關的重要變更。此檔案通常不使用，但可用於變更版本結構、更新淘汰政策等事項。

更新您的分支¶

當您進行作業時，可能需要將您本地的 main 分支更新為 main pip 存放庫中的 main 分支的最新版本，也就是維護者合併公關時前進的版本。專案上大部分的作業人員都使用下列工作流程。

這假設您已將 Git 設定好，以便在您執行下列命令時

git remote -v

您的輸出會顯示如下

origin  https://github.com/USERNAME/pip.git (fetch)
origin  https://github.com/USERNAME/pip.git (push)
upstream  https://github.com/pypa/pip.git (fetch)
upstream  https://github.com/pypa/pip.git (push)

在上面的範例中，USERNAME 是您在 GitHub 上的使用者名稱。

首先，擷取 main pip 存放庫 upstream 的最新變更

git fetch upstream

接下來，查閱您本地的 main 分支，並在上層重新設定變更

git checkout main
git rebase upstream/main

此時，您可能必須解決合併衝突。一旦完成，便將剛才對您本地的 main 分支進行的更新，推送到 GitHub 上的 origin 存放庫

git checkout main
git push origin main

現在您的本機 main 分支和 main 分支在您的 origin 儲存庫已更新為主 pip 儲存庫中的最新變更。

若要讓您的分支保持最新，過程類似

git checkout awesome-feature
git fetch upstream
git rebase upstream/main

現在您的分支已更新為上游 pip 儲存庫中 main 分支的最新變更。

在為分支工作時，將其推送到 GitHub 上的 origin 做為備份會是不錯的做法。若要推動分支，請執行這項指令

git push origin awesome-feature

在此範例中，<awesome-feature> 是您的分支名稱。這會將您正在作業的分支推送到 GitHub，但不會建立 PR。

一旦您已將分支推送到 origin，如果您需要再次更新它，您必須強制推動您的變更，方法是執行下列指令

git push -f origin awesome-feature

-f（或 --force）旗標在 push 之後將從您的本機分支強制更新以更新您的 origin 分支。如果您在分支上已開啟 PR，強制推動將會更新您的 PR。（當有人在 PR 上要求變更時，這是一個實用的指令。）

如果您收到這樣的錯誤訊息

! [rejected]        awesome-feature -> awesome-feature (non-fast-forward)
error: failed to push some refs to 'https://github.com/USERNAME/pip.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

嘗試使用 push -f 強制推動您的分支。

在主 pip 儲存庫中的 main 分支會經常更新，因此您可能必須在為分支作業時更新它至少一次。

感謝您的貢獻！

成為維護人員¶

如果您想成為一名正式維護人員，請先從提供協助開始。

作為第一步，我們歡迎您在 pip 的議題追蹤器上分類問題。pip 維護人員會提供分類能力給貢獻者，只要他們已參與一段時間（可能至少 2-3 個月），並對專案做出正面貢獻。這項分類是成為 pip 維護人員的選項，且強烈建議採用。

接下來，當您認為自己已準備好（可能在開始分類後至少 5 個月），請與其中一位維護人員聯繫，他們會在現有維護人員中發起投票。

請注意

成為維護人員後，該人應獲得權限，以存取跨多個平台的各種 pip 相關工具。維護人員可在此將這些工具記下以供未來參考

GitHub 推動權限
PyPI 發布權限
程式碼整合 (CI) 管理功能
ReadTheDocs 管理功能