Poetryへの貢献

Poetryへの貢献 #

まず、貢献していただきありがとうございます！

以下は、GitHubでPoetryに貢献するためのガイドラインです。これらはほとんどガイドラインであり、ルールではありません。最善の判断を下し、プルリクエストでこのドキュメントの変更を提案してください。

貢献方法 #

バグ報告 #

このセクションでは、Poetryのバグ報告を送信するためのガイドを説明します。これらのガイドラインに従うことで、メンテナーとコミュニティがあなたの報告を理解し、動作を再現し、関連する報告を見つけるのに役立ちます。

バグ報告を送信する前に #

一般的な質問と問題のリストについては、FAQを確認してください。
アップグレードの手順や既知の問題など、最近のリリースからのリリースノートについては、ブログを確認してください。
あなたの問題がissueトラッカーにまだ存在しないことを確認してください。
あなたの問題が本当にバグであり、DiscussionsまたはDiscordに適したサポートリクエストや質問ではないことを確認してください。

注意

あなたが経験していることと同じように見えるクローズされたissueを見つけた場合は、新しいissueを開き、新しいissueの本文に元のissueへのリンクを含めてください。

バグ報告を送信するにはどうすればよいですか？ #

Poetryとpoetry-coreに関するバグは、正しいissueテンプレートを使用して、メインのissueトラッカーに送信する必要があります。

問題を説明し、他の人が検索して理解できるようにします

問題点を特定するために、issueに明確で説明的なタイトルを使用してください。
問題を再現する正確なステップを、できるだけ詳しく説明してください。
ステップを実行した後に観察された動作を説明し、これがバグである理由を指摘してください。
代わりに表示されることを期待していた動作とその理由を説明してください。
予期しないエラーが発生した場合は、デバッグモード（-vvvフラグを使用）で問題のあるコマンドを実行してください。

issueを再現するための詳細な手順を提供します

プライベートパッケージリポジトリや名前などの潜在的なプライベート情報を削除した後、Gist、ペーストビン、またはサンプルリポジトリでpyproject.tomlファイルを提供してください。
issueを再現する手順を示す具体的な例を提供してください。これは、サンプルリポジトリ、コンテナで実行される一連のステップ、または非常に単純なケースのpyproject.tomlである可能性があります。
問題を確実に再現できませんか？その場合は、問題が発生する頻度と、通常どの条件下で発生するかについての詳細を提供してください。

次の質問に答えることで、より多くのコンテキストを提供します

問題は最近発生し始めましたか（例：Poetryの新しいバージョンに更新した後）、それとも常に問題でしたか？
問題が最近発生し始めた場合は、Poetryの古いバージョンで問題を再現できますか？問題が発生しない最新バージョンは何ですか？
あなたの環境について何かエキゾチックまたは異常なことはありますか？これには、特別なコンテナイメージの使用、Apple Siliconのような新しいCPUアーキテクチャ、またはネットワークトラフィックを傍受または変更する企業プロキシが含まれる可能性があります。

設定と環境に関する詳細を含めます

どのバージョンのPoetryを使用していますか？poetry --versionを実行すると、正確なバージョンを取得できます。
Poetryを実行するために使用されているPythonのバージョンは何ですか？poetry debug infoを実行して、この情報を取得します。
使用しているOSの名前とバージョンは何ですか？例には、Ubuntu 22.04やmacOS 12.6などがあります。

あなたの問題を理解し、再現する最良の機会を他の人に与えるために、再現手順に特別な努力を払うようにしてください。ローカル構成の問題を排除し、すべての再現を元のコンテナ（またはVM）で試行し、issueレポートでそのコンテナ/VM内で実行した手順を提供することにより、他の人があなたの問題をきれいに再現できるようにすることができます。

機能強化の提案 #

このセクションでは、既存の機能の改善だけでなく、完全に新しい機能を含む、Poetryの機能強化の提案を送信するためのガイドを説明します。これらのガイドラインに従うことで、メンテナーとコミュニティがあなたの提案を理解し、関連する提案を見つけるのに役立ちます。

機能強化の提案を送信する前に #

一般的な質問と問題のリストについては、FAQを確認してください。
あなたの問題がissueトラッカーにまだ存在しないことを確認してください。

機能強化の提案を送信するにはどうすればよいですか？ #

Poetryとpoetry-coreに関する機能強化の提案は、正しいissueテンプレートを使用して、メインのissueトラッカーに送信する必要があります。

提案を特定するために、issueに明確で説明的なタイトルを使用してください。
可能な場合は、具体的な手順や例を挙げて、提案された機能強化の詳細な説明を提供してください。
現在の動作を説明し、代わりにどのような動作を表示したいかとその理由を説明してください。

ドキュメントへの貢献 #

プロジェクトへの貢献を開始する最も簡単な方法の1つは、ドキュメントを改善することです。Poetryは常に進化しており、これは時々ドキュメントにギャップがあることを意味します。不足しているセクションを追加したり、既存のコンテンツをよりアクセスしやすくするために編集したり、チュートリアル、FAQなどの新しいコンテンツを作成したりすることで、役立つことができます。

注意

Github Discussionsとkind/questionラベルは、FAQ候補の優れたソースです。

ドキュメントに関するissueには、通常area/docsラベルが付いており、このWebサイトでレンダリングされた変更のプレビューもトリガーします。

コードの貢献 #

issueの選択 #

注意

初めての貢献者で、取り組むissueを探している場合は、候補となる貢献ページを見てみてください。私たちは初めての貢献者にとって良いissueをキュレーションするように最善を尽くしていますが、遅れているため、何も良いものが見当たらない場合は、お気軽にお問い合わせください。

issueに取り組みたい場合は、@python-poetry/triageをタグ付けしてissueにコメントしてください。私たちは、issueに関する解決策を喜んで話し合います。コードベースのナビゲーションに関するヘルプが必要な場合、取り組むものを探している場合、またはデザインや変更に関するフィードバックが必要な場合は、Discordサーバーに参加するか、Discussionを開始してください。

ローカル開発 #

Poetry は Poetry を用いて開発されています。 Poetry をローカル環境にインストールするには、ドキュメントを参照してください。

注意

Poetry の開発ツールチェーンには Python 3.8 以降が必要です。

まず、Poetry リポジトリをフォークし、ローカルにクローンする必要があります。これにより、プロジェクトに対してプルリクエストを作成できます。Git およびプルリクエストベースの開発が初めての場合は、GitHub が提供しているガイドが役立つでしょう。

次に、Poetry の依存関係をインストールし、テストスイートを実行して、すべてが期待どおりに動作することを確認する必要があります。

poetry install
poetry run pytest

Poetry に貢献する場合、コードがマージに適していることを確認するために自動化されたツールが実行されます。pytest に加えて、mypy を使用してコードの型チェックが正常に行われるようにする必要があります。

poetry run mypy

最後に、コードの一貫したスタイルを確保し、一般的なミスを根絶するために、多数のリンティングツールがコードで実行されます。pre-commitツールは、これらのツールをインストールして実行するために使用され、初回のみセットアップが必要です。

poetry run pre-commit install

pre-commit は、コミットを行うたびにコードを実行してチェックします。デフォルトでは、変更されたファイルでのみ実行されますが、すべてのファイルに対して手動で実行できます（pre-commit の設定を変更した場合に役立つ場合があります）。

poetry run pre-commit run --all-files

プルリクエスト #

プルリクエストの本文を完全に記入し、変更内容をできる限り正確に記述してください。プルリクエストの本文は、最終的なマージコミットおよび変更履歴エントリのベースとなるため、常に最新の状態に保つ必要があります。
プルリクエストに、変更または追加されたコードをカバーするテストが含まれていることを確認してください。一般的に、テストはコードがマージ可能とみなされるために必要であり、テストに合格していないコードはマージされません。
プルリクエストが mypy および pre-commit チェックに合格していることを確認してください。これらのツールは、リモート CI に依存するのではなく、ローカルで実行できることを忘れないでください。
変更によってドキュメントの変更が必要な場合は、プルリクエストでドキュメントも更新する必要があります。CI によって生成されたドキュメントのプレビューで、レンダリングの問題がないか確認してください。

注意

ブランチが最新のベースブランチに対してリベースされていることを確認してください。メンテナーは、プルリクエストをマージする前に、ブランチが最新であることを確認するように求める場合があります（特にベースブランチで CI の変更があった場合）、また、競合を修正するように求める場合もあります。

特に指示がない限り、すべてのプルリクエストは最初に main ブランチに受け入れられる必要があります。メンテナーは通常、他のブランチへのバックポートが必要かどうかを判断し、必要に応じて実行します。

Issue のトリアージ #

注意

注意が払われていない Issue がある場合は、Issue で @python-poetry/triage に ping を送信できます。まず、Issue に対応するのに妥当な時間を設け、特に Poetry チームに所属していない個人に直接 ping を送信することは避けてください。

報告された Issue のトリアージを手伝っている場合、このセクションでは、貢献に役立ついくつかの有用な情報を提供します。

トリアージの手順 #

Issue が関連する Poetry の領域とバージョンを特定し、適切なラベルを設定します（例：version/x.x.x、area/docs、area/venv）、そして status/triage ラベルを削除します。
（デバッグログ、pyproject.toml など）要求された情報が提供されておらず、関連性がある場合は、作者に要求します。
1. 作者からの返信を待っている間、status/waiting-on-response ラベルを設定します。
報告された Poetry バージョンで Issue を再現するか、作者にさらに明確化を要求します。
Issue がすでに解決されていないことを確認します。最新の安定版リリース、最新のプレリリース（存在する場合）、および開発ブランチで再現を試みます。
Issue を再現できない場合は、
1. Issue の作者に、より多くの再現手順と明確化を要求し、
2. status/needs-reproduction ラベルを設定し、
3. 再現がない場合は、Issue をクローズします。
Issue を再現できる場合は、
1. Issue で確認のコメントをし、
2. status/confirmed ラベルを設定し、
3. 可能であれば、Issue の根本原因を特定し、
4. 興味があれば、プルリクエストを通じて修正を試みます。

複数のバージョン #

Issue を再現しようとする場合、多くの場合、複数のバージョンの Poetry を同時に使用したいと思うでしょう。pipx を使うと、これが簡単にできます。

pipx install --suffix @1.2.1 'poetry==1.2.1'
pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1'
pipx install --suffix @main 'poetry @ git+https://github.com/python-poetry/poetry'
pipx install --suffix @local '/path/to/local/clone/of/poetry'

# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
poetry@main --version

注意

最新の変更が適用されていることを確認するために、使用する前に pipx upgrade poetry@main を実行することを忘れないでください。

注意

このメカニズムは、GitHub のプルリクエストのリモート参照を使用して、プルリクエストをテストするためにも使用できます。

pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head