貢献¶
Pip の内部¶
現在、pip の内部アーキテクチャに関するガイドを作成中です。これは、あなたが深く理解するのに役立つかもしれません。
プルリクエストの送信¶
main ブランチに対してプルリクエストを送信し、何をしているのか、なぜそうしているのかを明確に説明してください。pip に貢献するコードを配布する法的許可を持っている必要があり、MIT ライセンスの下で利用可能でなければなりません。
変更を網羅するテストを提供し、最初にローカルでテストを実行してください。pip は複数の Python バージョンとオペレーティングシステムをサポートしています。プルリクエストは、これらすべてのプラットフォームを考慮し、動作する必要があります。
プルリクエストは、レビューを容易にするために小さくする必要があります。自己完結型で、スコープを限定してください。研究によると、パッチサイズが大きくなるにつれてレビューの質が低下することが示されています。場合によっては、1 つの大きな機能を実装するために多くの小さな PR が必要になることがあります。特に、プルリクエストは、PR 内で継続的な開発作業が行われる「フィーチャブランチ」として扱われてはなりません。代わりに、機能は、個別にレビューおよびマージできる、より小さく独立した部分に分割する必要があります。
さらに、変更とは関係のないコードへの「 cosmetic 」な変更を含めないでください。これらは PR のレビューをより困難にするためです。例としては、コメントやドキュメント内のテキストのリフロー、行内の空白行や空白の追加または削除などがあります。このような変更は、必要に応じて、「フォーマットのクリーンアップ」PR として個別に行うことができます。
自動テスト¶
「main」ブランチへのすべてのプルリクエストとマージは、GitHub Actions を使用して、.github/workflows ファイルに基づいてテストされます。pip の継続的インテグレーションの詳細については、CI ドキュメントを参照してください。
プルリクエストの CI 実行のステータスと結果は、GitHub のプルリクエストの Web UI で確認できます。CI 実行が失敗し、出力を表示したい場合は、「詳細」リンクの形式で特定のビルドの CI サービスのページへのリンクを見つけることもできます.
プルリクエストに対して CI を再実行するには、プルリクエストを閉じて開き直すか、プルリクエストに別の変更を送信します。必要に応じて、プロジェクトのメンテナーはジョブ/ビルドの再起動を手動でトリガーできます。
pip の依存関係解決に関するより広範なソフトウェアアーキテクチャと、この機能を自動的にテストする方法については、次世代 pip 依存関係リゾルバーのテストを参照してください。
NEWS エントリ¶
NEWS.rst ファイルは towncrier を使用して管理されており、すべての重要な変更にはニュースエントリが添付されている必要があります。
ニュースファイルにエントリを追加するには、まず、行いたい変更を説明する課題を作成する必要があります。プルリクエスト自体がそのような機能を果たす場合もありますが、専用の課題を用意することをお勧めします (たとえば、コード品質の問題で PR が却下された場合など)。
課題またはプルリクエストを作成したら、その番号を取得し、news/ ディレクトリ内に、その課題番号にちなんで名付けられたファイルを作成し、removal、feature、bugfix、または doc の「タイプ」を関連付けます。
課題または PR 番号が 1234 で、この変更がバグを修正する場合、news/1234.bugfix.rst というファイルを作成します。PR は、複数のファイルを作成することで複数のカテゴリにまたがることができます (たとえば、機能を追加し、同時に古い機能を非推奨/削除した場合、news/NNNN.feature.rst と news/NNNN.removal.rst を作成します)。
PR が複数の課題/PR に関連する場合、それぞれにまったく同じ内容のファイルを作成でき、Towncrier はそれらを重複排除します。
NEWS エントリのコンテンツ¶
このファイルの内容は、ニュースファイルエントリのコンテンツとして使用される reStructuredText 形式のテキストです。towncrier は NEWS ファイルをレンダリングするときに影響を受けるすべての課題への参照を自動的に追加するため、エントリで課題または PR 番号を参照する必要はありません。ファイルの末尾に改行が必要です。
NEWS.rst ファイルで一貫したスタイルを維持するために、ニュースエントリは要点を押さえ、センテンスケースで、80 文字未満で、命令形にすることが推奨されます。エントリは「この変更は…になります」という文を完成させる必要があります。まれに、1 行では足りない場合は、命令形の要約行を使用し、その後に空白行を入れて、1 つ以上の段落で機能/変更の説明を区切ります。各段落は 80 文字で折り返します。ニュースエントリはエンドユーザー向けであり、エンドユーザーに関連する詳細のみを含める必要があることに注意してください。
NEWS エントリのタイプの選択¶
ささいな変更とは、ニュースファイルにエントリを必要としない変更のことです。たとえば、一般の人々に関する限り何も変更しないコードリファクタリング、タイプミス修正、空白の変更などです。PR をささいなものとしてマークするには、貢献者は news/ ディレクトリにランダムな名前の空のファイルを追加し、拡張子を .trivial.rst にするだけです。POSIX ライクなオペレーティングシステムを使用している場合は、touch news/$(uuidgen).trivial.rst を実行することで追加できます。Windows では、Powershell で New-Item "news/$([guid]::NewGuid()).trivial.rst" を使用して同じ結果を得ることができます。コアコミッターは、PR に「skip news」ラベルを追加することもできます。これにより、同じことが実現します。
ベンダーライブラリのアップグレード、削除、または追加は、news/<library>.vendor.rst ファイルを使用して特別な言及がされます。これは、このライブラリを取り込むことによって発生する可能性のある機能、バグ修正、またはその他の種類のニュースに加えてです。これはライブラリ名をキーとして使用するため、同じライブラリを 2 回更新しても 2 つのニュースファイルエントリは生成されません。
プロセス、ポリシー、またはその他の注目すべきコード以外の変更は、news/<name>.process.rst ファイルを使用して行うことができます。これは通常は使用されませんが、バージョンスキームの変更、非推奨ポリシーの更新などに使用できます。
ブランチの更新¶
作業中に、ローカルの 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 のユーザー名です。
まず、メイン pip リポジトリ upstream から最新の変更を取得します。
git fetch upstream
次に、ローカルの main ブランチをチェックアウトし、その上に変更をリベースします。
git checkout main
git rebase upstream/main
この時点で、マージの競合を解決する必要がある場合があります。これが完了したら、ローカルの main ブランチに行った更新を GitHub の origin リポジトリにプッシュします。
git checkout main
git push origin main
ローカルの main ブランチと、origin リポジトリの main ブランチが、pip メインリポジトリの最新の変更で更新されました。
ブランチを最新の状態に保つには、同様の手順に従います。
git checkout awesome-feature
git fetch upstream
git rebase upstream/main
これで、ブランチがアップストリーム pip リポジトリの main ブランチの最新の変更で更新されました。
作業中のブランチは、GitHub の origin にプッシュしてバックアップすることをお勧めします。ブランチをプッシュするには、次のコマンドを実行します。
git push origin awesome-feature
この例では、<awesome-feature> はブランチの名前です。このコマンドは、作業中のブランチを GitHub にプッシュしますが、プルリクエストは作成しません。
ブランチを origin にプッシュした後、再度更新する必要がある場合は、次のコマンドを実行して強制的にプッシュする必要があります。
git push -f origin awesome-feature
push の後の -f (または --force) フラグは、ローカルブランチからの更新を強制的に origin ブランチに反映します。ブランチにプルリクエストが開いている場合、強制プッシュによってプルリクエストが更新されます。(これは、プルリクエストに変更が要求された場合に役立つコマンドです。)
次のようなエラーメッセージが表示された場合
! [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 ブランチは頻繁に更新されるため、作業中に少なくとも 1 回はブランチを更新する必要がある場合があります。
貢献していただきありがとうございます！
メンテナになる¶
公式のメンテナになりたい場合は、まずお手伝いから始めてください。
最初のステップとして、pip のイシュートラッカーで issue のトリアージを行うことを歓迎します。pip のメンテナは、貢献者が一定期間（おそらく少なくとも 2〜3 か月）活動し、プロジェクトに積極的に貢献してきた場合、トリアージ権限を付与します。これは任意ですが、pip のメンテナになるためには強くお勧めします。
その後、準備ができたと思ったとき（おそらくトリアージを開始してから少なくとも 5 か月後）、メンテナのいずれかに連絡してください。既存のメンテナ間で投票が開始されます。
注記
メンテナになると、複数のプラットフォームにわたるさまざまな pip 関連ツールへのアクセス権が付与される必要があります。これらは、メンテナが将来参照できるように、ここに記載されています。
GitHub プッシュアクセス
PyPI 公開アクセス
CI 管理機能
ReadTheDocs 管理機能