注記

ドキュメントのこのセクションは現在執筆中です。pip 開発者は、このドキュメントを完成させるためのご協力をお待ちしております。ご協力いただける場合は、トラッキング課題でお知らせいただくか、プルリクエストを送信してそのトラッキング課題に言及してください。

課題トリアージ

これは、pip での課題追跡と、報告された課題のトリアージに役立つ方法を紹介します。

課題トラッカー

pip 課題トラッカーは、プロジェクトとともに GitHub でホストされています。

現在、課題トラッカーはバグ、機能リクエスト、一般的なユーザーサポートに使用されています。

pip 課題トラッカーでは、ラベルとマイルストーンを使用して作業を整理し、追跡します。

ラベル

課題ラベルは、以下の目的で使用されます。

  1. 課題の分類

  2. 貢献者と報告者のためのステータス情報の提供

  3. 貢献者が作業するタスクを見つけるのを支援

現在のラベルセットは、プレフィックスで識別されるいくつかのカテゴリに分けられています。

C - カテゴリ

機能リクエストまたは課題が pip 機能のどの領域に関連しているか

**K - 種類** **O - オペレーティングシステム** : OS 特有の課題の場合

P - プロジェクト/プラットフォーム

pip の外部のものに関連する

R - 解決策

これ以上の議論は実際には必要なく、アクションが特定されており、課題は待機中またはクローズされています

S - 状態

いくつかの自動ラベルや、作業が必要であることを示すその他の指標

種類

課題の役割または種類

各カテゴリに分類される具体的なラベルの説明は、ラベル ページに記載されています。

さらに、いくつかのスタンドアロンラベルがあります。

good first issue (初心者向け課題)

このラベルは、課題が初心者向けであることを示し、GitHub がリポジトリへの初回訪問者に表示するバナーに表示されます。

トリアージ

課題が作成されたときに付与されるデフォルトラベル

trivial (些細な)

ニュースファイルの要件を削除するプルリクエストのための特別なラベル

needs rebase or merge (リベースまたはマージが必要)

これは、BrownTruck がマージの競合がある PR をマークするために使用する特別なラベルです。

自動化

課題とプルリクエストを管理するためのヘルパーがいくつかあります。

課題トラッカーで作成された課題には、triage-new-issues ボットによって自動的に triage ラベルが付与されます。別のラベルが追加されると、ラベルは自動的に削除されます。

作者からのフィードバックが必要な課題には、S: awaiting response ラベルを付けることができます。作者が応答すると、no-response ボットがラベルを削除します。

課題がクローズされてから 30 日後、lock ボットが課題をロックし、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 debug: pip debug

  • pip version: pip -V

  • Python version: python -VV

  • Python path: python -c 'import sys; print(sys.executable)'

  • python on PATH: Unix: which python; Windows: where python

  • シェルによって解決された Python: type python

  • pip の由来 (get-pip.py、OS レベルのパッケージマネージャー、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. 明確な手順があれば、問題を報告している人と簡単に認識を合わせることができます。

問題を再現する最良の方法は、スクリプトを使用することです。

スクリプトはファイルにコピーして実行できますが、シェル出力は1行ずつ手動でコピーする必要があります。

問題を再現するためのスクリプトは、以下の条件を満たす必要があります。

  • 移植性が高い（UnixまたはWindowsであることを除き、システムに関する前提条件が少ない/ない）

  • 非破壊的である

  • 便利である

  • 実行者側でほとんど/まったく設定を必要としない

例

  • 異なるバージョンで複数のwheelを作成およびインストールする（リンク）

  • 認証エラーに小さなWebサーバーを使用する（リンク）

  • Dockerを使用してシステムまたはグローバル設定関連の問題をテストする（リンク）

  • Dockerを使用して特別なファイルシステム権限/構成をテストする（リンク）

  • get-pipでグローバルインストールにDockerを使用する（リンク）

  • /usr/lib64のないシステムでget-pipを実行する（リンク）

  • 現在の開発ブランチからpipを使用して再現する（リンク）

解決策に到達する

一部のユーザーサポートの質問は、pipよりもシステム構成に関連しています。これらの問題を他の問題と同じ注意と配慮を持って扱うことが重要です。具体的には、

  1. 問題が非常に古く、ユーザーがアクティブでないように見える場合を除き、問題をクローズする前に確認を待ちます。

  2. ユーザーを質問に最適なフォーラムに誘導します。

  3. ユーザーサポートの質問が他のフォーラムを使用して解決するのが最適であっても、私たちが物事を容易にすることができないわけではありません。ユーザーのクエリから、より良い警告やエラーメッセージなどで、どのようにすればユーザーやあなたにとって物事を容易にすることができたかを理解するように努めてください。そのケースをカバーする問題が存在しない場合は、問題を作成します。問題が存在する場合は、この問題をクローズする前に、その問題を参照するようにしてください。

  4. ユーザーがパッケージのインストールに問題を抱えている可能性があり、パッケージのsetup.pyまたはビルドバックエンドの構成が複雑な場合があります。これらの場合、トラブルシューティングを支援できますが、最良のアドバイスは、関連プロジェクトのサポートチャネルに誘導することです。

  5. それが一方の原因または別の原因であると性急に決めつけないでください。他人の問題のように見えるものでも、pipの問題であるか、少なくとも改善できる可能性があります。

  6. Pythonパッケージに関する一般的な議論については、

問題をクローズする

問題は、以下の場合に解決済みと見なされ、クローズされる可能性があります。

  • 問題の議論で示されている考えられる改善点または問題点ごとに、

    • 特定の行動について合意に達し、その行動がプロジェクトの外部のものであり、その後プロジェクトでフォローアップが必要ないと思われる場合。

      • PEPの更新（python/pepsの対応する問題あり）

      • 既に別の問題によって追跡されている

    • プロジェクト固有の問題が特定され、メインブランチの最新のコミットでは問題が発生しなくなった。

  • 機能拡張または機能リクエストに支持者がおらず、メンテナーはそれをオープンにしておく価値がないと考えている。

  • 問題が重複として識別され、明らかに重複である場合（つまり、元のレポートが非常に優れており、問題を直接指し示している場合）

  • 問題が修正され、問題ではなくなったことが独自に検証できる場合。これがコードによるものである場合、それに至った具体的な変更/PRを特定し、追跡のために投稿する必要があります。

よくある問題

  1. ネットワーク関連の問題 - 再試行、アドレス検索などが関係する問題は、通常はネットワークの問題です。

  2. 複数のPythonバージョンがあること、またはOSパッケージマネージャーで管理されているpip/pythonインストール（特にDebian/Ubuntu）に関連する問題。これらは通常、次のように現れます。

    1. インストール済みパッケージが見つからない

    2. 基本的なライブラリが見つからない、基本的なOSコンポーネントがない

    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`