備註

此文件文件部分目前仍撰寫中。歡迎 pip 開發者協助完成此文件。如果您有興趣協助，請讓我們在 追蹤問題 中知道，或提交拉取要求，並在追蹤問題中提到。

問題分流

這作為 pip 問題追蹤的簡介，以及如何協助分流回報的問題。

問題追蹤器

The pip 問題追蹤器 是與專案一起在 GitHub 中架設。

目前，問題追蹤器是用於臭蟲、功能要求和一般使用者支援。

在 pip 問題追蹤器中，我們使用標籤和里程碑來組織和追蹤工作。

標籤

問題標籤用於

  1. 分類問題

  2. 提供進度資訊給貢獻者和回報者

  3. 協助貢獻者找出工作事項

目前的標籤組依據前綴分類為幾個類別

C - 類別

功能要求或問題相關的 pip 功能的哪個部分

K - 類型 O - 作業系統：針對特定作業系統的問題

P - 專案/平台

相關於 pip 外部事項

R - 解決方案

真的不需要更多討論，已找出一個動作，而且問題正在等待或已關閉

S - 狀態

針對一些自動標籤和其他指標，說明需要執行工作

類型

問題的角色或性質

屬於每個類別的特定標籤都有說明，可以在 標籤 頁面看到。

此外，還有幾個獨立標籤

良好的開場問題

此標籤將問題標示為初學者友善，而且會顯示在 GitHub 顯示給首次造訪儲存庫的訪客的橫幅中

分流

當建立問題時給予的預設標籤

瑣碎

移除 新聞檔案需求 的拉取要求之特殊標籤

需要重新訂正底層或合併

這是 BrownTruck 用來標示有合併衝突的 PR 的特殊標籤

自動化

有幾個輔助程式可管理問題和拉取要求。

triage 標籤會由 triage-new-issues bot 自動分配給問題追蹤器上建立的問題。當加上其他標籤時，triage 標籤會自動移除。

當問題需要作者回饋，我們可以用 S: awaiting response 標籤標示。作者回應後，no-response bot 會移除該標籤。

問題關閉 30 天後，lock bot 會鎖定問題並加入 S: auto-locked 標籤。這讓我們不用繼續追蹤已關閉的問題，但問題引用和連結無法顯示於已關閉的問題。

分類問題

使用者建立問題的原因有多種

  1. 提出可加入或改善的 pip 功能建議

  2. pip 使用問題

  3. pip 使用不便疑慮

  4. 使用 pip 可解決的一般套件管理問題

  5. 安裝或使用 Python 套件的問題

  6. 管理虛擬環境的問題

  7. 管理 Python 安裝的問題

分類問題意指界定問題類型，並

  • 確認錯誤

  • 提供支援

  • 討論和設計工具用法

具體而言，處理問題的方法為

  1. 閱讀問題標題

  2. 查看問題說明

  3. 提出問題

  4. 如果時間允許，嘗試再現

  5. 搜尋或記住相關問題，並連結到問題

  6. 找出適當的關注領域（如果適用）

請注意，所有溝通都與他人進行，並且應依照 行為準則 進行。

問題（錯誤或支援）的循環通常如下

  1. 等待分類（加上 triage 標籤）

  2. 確認問題 - 與使用者討論、收集細節、嘗試再現問題（可能會加上特定類別，S: awaiting-response、S: discussion-needed、或 S: need-repro）

  3. 已確認 - 以簡單且一致的方式重複再現問題，或找出導致問題的機制

  4. 等待修復 - 已確認修復方式，且無需對問題多做討論，應標示 R: awaiting PR

  5. 已關閉 - 可能有幾個原因

    • 已修復

    • 無法再現，且無法取得更多細節，也無法進行其他動作

    • 實際問題是其他專案或與系統設定相關，pip 無法（或不會）適當地調整

請求資訊

請求更多資訊以更清楚了解導致問題的脈絡和環境。在此列舉一些可能會在不同情況下有用的特定資訊範例

  • pip 除錯：pip debug

  • pip 版本：pip -V

  • Python 版本：python -VV

  • Python 路徑：python -c 'import sys; print(sys.executable)'

  • python 於 PATH：Unix：which python；Windows：where python

  • 由指令殼解析的 Python：type python

  • pip 的來源（get-pip.py、作業系統級套件管理員、ensurepip、手動安裝）

  • 使用虛擬環境（以及 --system-site-packages 嗎？）

  • 使用 Conda 環境

  • PATH 環境變數

  • 網路狀況（例如，空氣間隙環境、防火牆）

  • --verbose 失敗指令的輸出

  • （Unix）strace 失敗指令的輸出（小心不要輸出至已安裝套件的目錄，否則 pip 會一直複製記錄檔…）

  • （Windows）procmon 失敗指令期間的輸出（範例請求）

  • 與問題相關的檔案清單（例如，ls -l venv/lib/pythonX.Y/problem-package.dist-info/）

  • 意外行為是否曾正常運作 - 若有，則設定的詳細資料為何（同上述資訊）

通常，若資訊能協助確認或排除可能的錯誤來源，則建議請求提供資訊。我們不應請求無法改善我們對情況了解的資訊。

複製問題

當問題發生且原因不明確時，我們必須能獨立複製此問題，這項工作有好幾個目的

  1. 如果是一個 pip 錯誤，則任何修正程式都需要測試，而良好的再現性已完成大部分。

  2. 如果無法使用提供的說明進行再現，則有助於排除很多可能的原因。

  3. 明確的說明集是一種輕鬆的方式，可以與報告問題的人員達成共識。

再現問題的最佳方式是使用指令碼。

指令碼可複製到一個檔案並執行，而 shell 輸出必須逐行手動複製。

再現問題的指令碼應該

  • 具備可移植性（少數或不對系統假設，只要適用於 Unix 或 Windows 即可）

  • 不具破壞性

  • 便利

  • 執行人員所需設定很少或根本無需設定

範例

  • 建立並安裝含有不同版本的安裝包 (連結)

  • 使用小型網路伺服器來進行驗證錯誤 (連結)

  • 使用 Docker 來測試系統或全球組態相關問題 (連結)

  • 使用 Docker 來測試特殊的檔案系統權限/組態 (連結)

  • 使用 Docker 進行全球安裝與 get-pip (連結)

  • 在沒有 /usr/lib64 的系統上使用 get-pip (連結)

  • 使用來自當前開發分支的 pip 進行再現 (連結)

達成問題解決

某些使用者支援問題與系統組態的關聯性高於 pip。以與其他問題相同的謹慎和專心對待這些問題特別重要，具體來說

  1. 除非問題非常舊且使用者看似不活躍，否則在關閉問題之前等待確認

  2. 引導使用者前往最適合其問題的論壇

  3. 即便透過使用其他論壇最能解決使用者支援問題，並不代表我們無法讓事情變得更簡單。嘗試從使用者查詢中摘取並了解如何讓使用者或您更容易了解，例如改善警告或錯誤訊息。如果沒有涵蓋該案例的問題，請建立一個。如果問題存在，請務必在關閉此問題之前參照該問題。

  4. 使用者可能會在安裝套件時遭遇麻煩，其中套件 setup.py 或建置後端設定不是那麼容易。在這些情況下，我們可以提供協助進行故障排除，但最好的建議是將使用者轉至相關專案的支援管道。

  5. 不要急於假設是某一個原因。看起來像是別人的問題，仍然可能是 pip 中的問題，或至少是具有改善空間的一部分。

  6. 一般 Python 封裝討論

關閉問題

問題在以下情況下可以視為已解決且關閉

  • 對於問題討論中所提出的每一個可能的改善或問題

    • 達成特定行動的共識，且行動看來是針對專案外部的，此後專案中不必進一步追蹤。

      • PEP 更新（在 python/peps 中有相應問題）

      • 已由另一個問題追蹤

    • 已找出特定於專案的問題，且此問題在主分支的最新提交中不再發生。

  • 增強或功能要求不再有支持者，且維護人員認為將其保留開啟的價值不大。

  • 問題已被找出為重複的，且很明顯是重複的（即原始報告寫得很好，且直接指出問題所在）

  • 問題已修復，且可以獨立驗證為不再是有問題的。如果這是透過程式碼，則應找出導致此問題的特定變更或公關，並張貼出來以進行追蹤。

常見問題

  1. 與網路相關的問題，任何涉及重試、地址查詢或類似問題的問題，通常都是網路問題。

  2. 與擁有多個 Python 版本或 OS 套件管理員管理的 pip/python 安裝（特別是使用 Debian/Ubuntu 的情況）相關的問題。這些問題通常會以以下方式呈現

    1. 找不到已安裝的套件

    2. 找不到基本函式庫、少了基本作業系統元件

    3. 在這些情況下，您會想要確保知道他們是如何取得 Python 和 pip。知道相關的套件管理員命令會有幫助，例如 dpkg -S。

對於由重新發行者變更所造成的問題

某些問題是由 Python/pip 的重新發行者對 Python/pip 所做的修補程式所造成的。

某些重新發行者共用偏好的用語法來將使用者重新導向至其問題追蹤器。

Fedora、RHEL、CentOS（以及其他衍生版本，例如 Rocky、Scientific、CloudLinux）

This issue looks like it's caused by changes that Fedora or Red Hat
made in their pip packaging. Please file a Fedora bug at
https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=python-pip

cc @encukou @hroncok

Debian

This issue looks like it's caused by changes that Debian made in
their pip packaging. Please file a bug with Debian, with
`reportbug python3-pip` [Docs](https://www.debian.org/Bugs/Reporting).
You can link to this issue in your bug report.

In the meantime, you may be able to work-around your issue by upgrading
pip inside your virtualenv: `python -m pip install -U pip`

Ubuntu

This issue looks like it's caused by changes that Ubuntu made in
their pip packaging. Please file a bug with Ubuntu, with
`ubuntu-bug python3-pip` [Docs](https://help.ubuntu.com/community/ReportingBugs).
You can link to this issue in your bug report.

In the meantime, you may be able to work-around your issue by upgrading
pip inside your virtualenv: `python -m pip install -U pip`