pandas への貢献#

すべての貢献、バグレポート、バグ修正、ドキュメントの改善、機能拡張、アイデアを歓迎します。

バグレポートと機能拡張リクエスト#

バグレポートと機能拡張リクエストは、pandas をより安定させるための重要な要素であり、Github issue を通じて管理されています。issue やリクエストを報告する際は、適切なカテゴリを選択し、issue フォームにすべて記入して、他の人とコア開発チームが issue の範囲を完全に理解できるようにしてください。

issue は pandas コミュニティに表示され、他の人からのコメントやアイデアを受け付けることができます。

貢献する Issue を見つける#

pandas やオープンソース開発に慣れていない場合は、GitHub の「issues」タブを検索して、興味のある issue を見つけることをお勧めします。担当者が割り当てられていない、Docs と good first issue のラベルが付いた issue は、通常、新しいコントリビューターに適しています。

興味深い issue を見つけたら、他の誰かが重複して作業しないように、issue を自分に割り当てることをお勧めします。Github issue で、take というテキストだけのコメントを投稿すると、自動的に issue が割り当てられます（数秒かかり、表示されるまでにページの更新が必要になる場合があります）。

何らかの理由で issue の作業を続行できない場合は、他の人が利用可能であることがわかるように、割り当てを解除してください。割り当てられた issue のリストを確認できます。なぜなら、人々はもはやそれらに取り組んでいない可能性があるからです。割り当てられている issue に取り組みたい場合は、現在の担当者に引き継いでもいいか、丁寧に尋ねてください（issue の作業が中止されたと見なす前に、少なくとも 1 週間の非アクティブ期間を設けてください）。

私たちは、いくつかのコントリビューターコミュニティコミュニケーションチャネルを持っており、参加して質問することを歓迎します。その中には、新しいコントリビューター向けの定期的な会議、開発会議、開発メーリングリスト、コントリビューターコミュニティ向けの Slack などがあります。すべての pandas コントリビューターは、これらのスペースで歓迎され、互いにつながることができます。長年私たちと一緒にいるメンテナーでさえ、始めたばかりの頃はあなたと同じように感じており、私たちがどのように仕事をしているのか、どこに何があるのかを知るにつれて、あなたを歓迎し、サポートさせていただきます。詳細については、次のセクションをご覧ください。

プルリクエストの送信#

バージョン管理、Git、GitHub#

pandas はGitHubでホストされており、貢献するには、無料の GitHub アカウントにサインアップする必要があります。私たちは、多くの人がプロジェクトで一緒に作業できるように、バージョン管理にGitを使用しています。

Git に慣れていない場合は、Git を学ぶためのこれらのリソースを参照できます。必要に応じて、コントリビューターコミュニティに連絡して支援を求めてください。

また、プロジェクトは、このページでさらに説明されているフォーキングワークフローに従います。コントリビューターはリポジトリをフォークし、変更を加えてからプルリクエストを作成します。したがって、このガイドのすべての指示を読んで従ってください。

GitHub でフォークを通じてプロジェクトに貢献するのが初めての場合は、GitHub のプロジェクトへの貢献に関するドキュメントをご覧ください。GitHub は、テストリポジトリを使用して簡単なチュートリアルを提供しています。リポジトリのフォーク、フォークのクローン作成、フィーチャーブランチの作成、変更のプッシュ、プルリクエストの作成に慣れるのに役立つ場合があります。

GitHub でのフォークとプルリクエストの詳細については、以下の役に立つリソースをご覧ください。

Git の概要#

GitHub には、git のインストール、SSH キーの設定、git の構成に関する手順があります。ローカルリポジトリと GitHub 間でシームレスに作業するには、これらの手順をすべて完了する必要があります。

pandas のフォークを作成する#

コードを操作するには、pandas の独自のコピー（別名フォーク）が必要です。pandas プロジェクトページに移動し、Fork ボタンをクリックします。Create Fork を選択する前に、main ブランチのみをコピーするチェックボックスをオフにしてください。フォークをマシンにクローンしたい場合

git clone https://github.com/your-user-name/pandas.git pandas-yourname
cd pandas-yourname
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream

これにより、ディレクトリ pandas-yourname が作成され、リポジトリがアップストリーム（メインプロジェクト）の *pandas* リポジトリに接続されます。

注意

浅いクローンを実行すると（--depth==N、1 以上の N で）、バージョン番号を計算できなくなるため、一部のテストと機能が pd.show_versions() と同様に壊れる可能性があります。

フィーチャーブランチの作成#

ローカルの main ブランチは、常に pandas リポジトリの現在の状態を反映している必要があります。最初に、メインの pandas リポジトリで最新の状態になっていることを確認します。

git checkout main
git pull upstream main --ff-only

次に、変更を加えるためのフィーチャーブランチを作成します。例えば

git checkout -b shiny-new-feature

これは、作業ブランチを main から shiny-new-feature ブランチに変更します。このブランチの変更は、1 つのバグまたは機能に固有のものにして、ブランチが pandas に何をもたらすかを明確にします。git checkout コマンドを使用して、多くのフィーチャーブランチを持ち、それらを切り替えることができます。

ブランチを作成した後に、main の変更でフィーチャーブランチを更新する場合は、PR の更新に関するセクションを確認してください。

コードの変更#

コードを変更する前に、貢献環境ガイドラインに従って、適切な開発環境をセットアップしてください。

コードを変更したら、現在行っているすべての変更を次のように実行して確認できます。

git status

変更または追加しようとしたファイルについては、次を実行します。

git add path/to/file-to-be-added-or-changed.py

git status を再度実行すると、次のように表示されます。

On branch shiny-new-feature

     modified:   /relative/path/to/file-to-be-added-or-changed.py

最後に、説明的なコミットメッセージとともに、変更をローカルリポジトリにコミットします。

git commit -m "your commit message goes here"

変更のプッシュ#

変更を GitHub ページに公開表示する場合は、フォークされたフィーチャーブランチのコミットをプッシュします。

git push origin shiny-new-feature

ここで、origin は GitHub のリモートリポジトリに付けられたデフォルトの名前です。リモートリポジトリを表示できます。

git remote -v

上記のようにアップストリームリポジトリを追加した場合、次のようなものが表示されます。

origin  [email protected]:yourname/pandas.git (fetch)
origin  [email protected]:yourname/pandas.git (push)
upstream        git://github.com/pandas-dev/pandas.git (fetch)
upstream        git://github.com/pandas-dev/pandas.git (push)

これでコードは GitHub にありますが、まだ pandas プロジェクトの一部ではありません。それが実現するには、GitHub でプルリクエストを送信する必要があります。

プルリクエストの作成#

コードの変更が完了したら、コードの変更はpandas 貢献ガイドラインに従って正常に受け入れられる必要があります。

すべて問題なければ、プルリクエストを作成する準備ができています。プルリクエストは、ローカルリポジトリのコードを GitHub コミュニティがレビューしてプロジェクトにマージし、次のリリースに表示されるようにする方法です。プルリクエストを送信するには

  1. GitHub のリポジトリに移動します。

  2. Compare & pull request ボタンをクリックします。

  3. その後、コミット と 変更されたファイル をクリックして、すべてが問題ないことを最後に確認できます。

  4. プレフィックスを含む記述的なタイトルを記述します。pandas は、タイトルのプレフィックスに規則を使用します。一般的なプレフィックスと、それらをいつ使用するかについての一般的なガイドラインを以下に示します。

    • ENH: 機能強化、新機能

    • BUG: バグ修正

    • DOC: ドキュメントの追加/更新

    • TST: テストの追加/更新

    • BLD: ビルドプロセス/スクリプトの更新

    • PERF: パフォーマンスの向上

    • TYP: タイプアノテーション

    • CLN: コードクリーンアップ

  5. ディスカッションのプレビュー タブに変更内容の説明を記述します。

  6. プルリクエストを送信 をクリックします。

このリクエストはリポジトリのメンテナに送られ、コードがレビューされます。

プルリクエストの更新#

プルリクエストに対するレビューに基づいて、コードにいくつかの変更を加える必要があるでしょう。フィードバックに対処し、プルリクエストを更新するには、コードコミットの手順 に再度従ってください。

pandas の main ブランチの更新をプルリクエストに反映することも重要です。フィーチャブランチを pandas の main ブランチの変更で更新するには、以下を実行します。

git checkout shiny-new-feature
git fetch upstream
git merge upstream/main

競合がない場合（または自動的に修正できた場合）、デフォルトのコミットメッセージを含むファイルが開きます。このファイルを保存して終了するだけで済みます。

マージの競合がある場合は、それらの競合を解決する必要があります。その方法については、たとえば https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ を参照してください。

競合が解決したら、以下を実行します。

  1. git add -u で、更新したファイルをステージングします。

  2. git commit で、マージを完了します。

注意

ブランチを main で更新したいときにコミットされていない変更がある場合は、更新する前に stash する必要があります（stash のドキュメント を参照）。これは事実上、変更を保存し、更新後に再適用できます。

フィーチャブランチがローカルで更新されたら、GitHub のブランチにプッシュすることでプルリクエストを更新できます。

git push origin shiny-new-feature

git push を実行すると、プルリクエストがブランチの変更で自動的に更新され、継続的インテグレーション チェックが再開されます。

開発環境の更新#

ローカルの main ブランチを pandas の main ブランチの更新で定期的に更新し、開発中に使用されるさまざまなパッケージの変更を反映するように開発環境を更新することが重要です。

mamba を使用している場合は、以下を実行します。

git checkout main
git fetch upstream
git merge upstream/main
mamba activate pandas-dev
mamba env update -f environment.yml --prune

pip を使用している場合は、以下を実行します。

git checkout main
git fetch upstream
git merge upstream/main
# activate the virtual environment based on your platform
python -m pip install --upgrade -r requirements-dev.txt

プルリクエストを成功させるためのヒント#

プルリクエストの作成 フェーズまで到達した場合、コアコントリビューターの1人が確認する可能性があります。ただし、少人数の人々がすべてのコントリビューションのレビューを担当しているため、ボトルネックが発生することがよくありますのでご注意ください。

プルリクエストがレビューされる可能性を高めるには、以下を行う必要があります。

  • 未解決の issue を参照する ことで、重要な変更の目的を明確にします。

  • 適切なテストがあることを確認する。これは、PR の最初の部分である必要があります。

  • プルリクエストをできるだけシンプルにする。大規模な PR はレビューに時間がかかります。

  • CI が正常な状態であることを確認する。そうでない場合、レビュー担当者は確認しない可能性があります。

  • プルリクエストの更新 を続ける。リクエストに応じて、または数日ごとに更新します。