pandas メンテナンス#

このガイドは、pandas のメンテナー向けです。また、pandas の開発プロセスや、メンテナーになるために必要なステップを理解したいと考えているコントリビューターにとっても興味深いかもしれません。

主な貢献ガイドは、pandas への貢献で入手できます。

役割#

pandas は、2つのレベルの権限を使用します。トリアージとコアチームメンバーです。

トリアージメンバーは、issue や pull request にラベルを付けたり、閉じたりすることができます。

コアチームメンバーは、issue や pull request にラベルを付けたり、閉じたりできるだけでなく、pull request をマージすることもできます。

GitHub は、権限の完全なリストを公開しています。

タスク#

pandas は主にボランティアプロジェクトであるため、これらのタスクは、トリアージ担当者やメンテナーの「期待」として解釈されるべきではありません。むしろ、メンテナーとはどういうことかを一般的に説明するものです。

  • 新規に提出された issue のトリアージ（Issue のトリアージを参照）

  • 新たに開かれた pull request のレビュー

  • 既存の issue や pull request の更新への対応

  • 停滞した issue や pull request に関する議論と意思決定の推進

  • 一貫性と保守性を確保するための API 設計に関する質問への経験/知恵の提供

  • プロジェクト組織（開発者会議の開催/参加、pandas の代表）

https://matthewrocklin.com/blog/2019/05/18/maintainer は、背景知識として興味深いかもしれません。

Issue のトリアージ#

トリアージは、コミュニティから報告された issue に対応するための重要な最初のステップであり、部分的な貢献であっても、pandas のメンテナンスに役立つ素晴らしい方法です。以下のすべてのステップが完了したら、「Needs Triage」タグを削除してください。

新しく開かれた issue をトリアージする際の一般的なワークフローを以下に示します。

  1. issue を開いてくれたことに感謝する

    issue トラッカーは、ライブラリを使用するだけでなく、pandas プロジェクト自体との多くの人々の最初の対話です。そのため、歓迎され、気持ちの良い経験になるようにしたいと考えています。

  2. 必要な情報が提供されているか？

    理想的には、報告者は issue テンプレートに記入してくれるはずですが、そうでない人も多いです。（使用した pandas のバージョンなど）重要な情報が欠落している場合は、遠慮なくそれを求め、「Needs info」というラベルを issue に追加してください。報告は、バグレポートと機能拡張リクエストのガイドラインに従う必要があります。テンプレートに従わなかった場合は、そこにリンクするとよいでしょう。

    タイトルが issue を正確に反映していることを確認してください。不明確な場合は自分で編集してください。

  3. これは重複した issue か？

    多くの issue が開かれています。新しい issue が明らかに重複している場合は、新しい issue に「Duplicate」というラベルを付け、元の issue へのリンクとともに issue を閉じます。報告者には感謝し、元の issue に意見を述べたり、修正を試みたりすることを勧めてください。

    新しい issue が、より良い例や少し異なる例などの関連情報を提供している場合は、元の issue にコメントとして追加するか、元の投稿を編集してください。

  4. issue は最小限で再現可能か？?

    バグレポートの場合、報告者は最小限の再現可能な例を提供することが求められます。https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports で分かりやすく説明されています。例が再現可能でない場合、または明らかに最小限でない場合は、例を提供したり、提供された例を簡略化したりできるかどうかを遠慮なく報告者に尋ねてください。最小限の再現可能な例を作成するのが大変な作業であることを認識してください。報告者が苦労している場合は、自分で作成を試み、元の投稿を編集して含めることができます。

    再現可能な例を提供できない場合は、「Needs info」ラベルを追加します。

    再現可能な例が提供されたが、簡略化できる場合は、より簡単な再現可能な例で元の投稿を編集します。

    issue が main ブランチに存在することと、すべてのステップが完了するまで「Needs Triage」タグが付いていることを確認してください。main ブランチに存在することを確認したら、issue にコメントを追加して、他の人が確認済みであることを把握できるようにします。

  5. これは明確に定義された機能リクエストか？

    一般的に、pandas は、pull request が作成される前に、issue で新機能について議論し、設計することを好みます。新しい機能の提案された API を含めるように提出者に促してください。完全な docstring を書くことは、詳細を明確にするのに適した方法です。

    新しい機能リクエストには、「Needs Discussion」というタグを付けてください。提案が pandas の範囲内であるかどうかを決定する前に、複数の pandas メンテナーからの議論が必要になるためです。

  6. これは使い方の質問か？

    使い方の質問は、pandas タグ付きで StackOverflow で質問することを推奨します。https://stackoverflow.com/questions/tagged/pandas

    簡単に答えられる場合は、関連するドキュメントのセクションへのリンクを提供し、今後はこの種の質問は StackOverflow で行うべきであることを伝え、issue を閉じてください。

  7. どのラベルとマイルストーンを追加する必要があるか？

    関連するラベルを適用します。これは少し芸術的なものであり、経験が必要です。同様の issue を見て、どのようにラベル付けされているかを感じてください。

    issue が明確に定義されており、修正が比較的簡単そうに見える場合は、issue に「Good first issue」というラベルを付けます。

    上記を完了したら、「needs triage」ラベルを削除してください。

リグレッションの調査#

リグレッションとは、以前は正常に動作していたコードを意図せずに破損させるバグのことです。リグレッションを調査する一般的な方法は、git bisect を使用することです。これにより、バグを引き起こした最初のコミットを特定できます。

例：ユーザーが、pandas バージョン 1.5.0 では pd.Series([1, 1]).sum() が 3 を返すのに対し、バージョン 1.4.0 では 2 を返すと報告します。まず、pandas ディレクトリに t.py というファイルを作成します。ファイルには以下が含まれます。

import pandas as pd
assert pd.Series([1, 1]).sum() == 2

次に、以下を実行します。

git bisect start
git bisect good v1.4.0
git bisect bad v1.5.0
git bisect run bash -c "python setup.py build_ext -j 4; python t.py"

これにより、動作を変更した最初のコミットが特定されます。C 拡張機能をすべてのステップで再構築する必要があるため、検索に時間がかかる場合があります。

bisect を終了し、現在のバージョンを再構築します。

git bisect reset
python setup.py build_ext -j 4

対応する issue で調査結果を報告し、コミット作成者に連絡して意見を聞いてください。

注意

上記の bisect run コマンドでは、t.py が 0 で終了する場合はコミットが良好とみなされ、それ以外の場合は不良とみなされます。例外を発生させることが望ましい動作の場合は、コードを適切な try/except ステートメントで囲みます。その他の例については、GH 35685 を参照してください。

issue を閉じる#

ここでは慎重にしてください。多くの人が、issue を閉じることは、会話が終了したと解釈します。通常、動作がバグではないと判断されたり、機能が範囲外であると判断された場合は、報告者に返信するか、自分で issue を閉じるための時間を与えるのが最善です。ただし、報告者がいなくなることもあり、会話が途絶えたら issue を閉じます。issue を閉じるべきだと思うが、完全に確信がない場合は、「closing candidate」ラベルを適用し、他のメンテナーが確認するのを待ってください。

pull request のレビュー#

pull request は、通常のコントリビューター、トリアージ担当者、またはコアチームメンバーであれば、誰でもレビューできます。ただし、コアチームメンバーのみが、準備ができたときに pull request をマージできます。

pull request をレビューする際に確認すべき点を以下に示します。

  • テストは、密接に関連するテストと同じファイル内の適切な場所に配置する必要があります。

  • 新しいパブリック API は、doc/source/reference/ のどこかに含める必要があります。

  • 新しく変更された API は、docstring で versionadded または versionchanged ディレクティブを使用する必要があります。

  • ユーザー向けの変更は、適切なファイルの whatsnew に記述する必要があります。

  • リグレッションテストは、# GH-1234 のように、元の GitHub issue 番号を参照する必要があります。

  • pull request にはラベルが付けられ、適切なマイルストーン（リグレッションの修正および小さなバグの修正の場合は次のパッチリリース、それ以外の場合は次のマイナーマイルストーン）が割り当てられている必要があります。

  • 変更は、バージョンポリシーに準拠する必要があります。

バックポート#

pandas は、次の目的でポイントリリース（例：1.4.3）をサポートしています。

  1. 最初のマイナーバージョンリリースで導入された新機能のバグを修正します。

  • 例：1.4 で新しい機能が追加され、バグが含まれている場合は、1.4.3 で修正を適用できます。

  1. 以前のマイナーリリースで動作していたバグを修正します。バックポートが適切であるというコアチームメンバー間の合意が必要です。

  • 例：1.2 で機能が動作し、1.3 以降で動作しなくなった場合は、1.4.3 で修正を適用できます。

pandasのマイナーリリースはGitHubのブランチに基づいているため（例：1.4のポイントリリースは1.4.xブランチに基づいている）、「バックポート」とは、プルリクエストの修正をmainブランチと、次のポイントリリースに関連付けられた正しいマイナーブランチにマージすることを意味します。

デフォルトでは、プルリクエストがGitHubインターフェース内で次のポイントリリースマイルストーンに割り当てられている場合、プルリクエストがマージされると、@meeseeksdevボットによってバックポートプロセスが自動的に実行されるはずです。プルリクエストを正しいバージョンのブランチにバックポートする新しいプルリクエストが作成されます。マージの競合により、手動でコードの競合に対処するプルリクエストを作成する必要がある場合があります。

ボットが自動的にバックポートプロセスを開始しない場合は、マージされたプルリクエストにGitHubのコメントを書いて、バックポートをトリガーすることもできます。

@meeseeksdev backport version-branch

これにより、特定の変更をブランチにバックポートするワークフローがトリガーされます（例：@meeseeksdev backport 1.4.x）。

古いissueの整理#

pandasで未解決のissueはすべてコストがかかります。未解決のissueがあると、重複を見つけるのが難しくなり、pandasで何をする必要があるかを知るのが難しくなる可能性があります。とはいえ、issueをクローズすること自体が目標ではありません。私たちの目標は、pandasを可能な限り最高の状態にすることであり、それは未解決のissueの質が高いことを保証することによって最もよく達成されます。

場合によっては、バグは修正されたものの、issueがプルリクエストにリンクされていないことがあります。このような場合は、「これは修正されましたが、テストが必要です。」とコメントし、issueに「Good First Issue」と「Needs Test」のラベルを付けます。

古いissueがissueテンプレートに従っていない場合は、元の投稿を編集して、最小限の例、実際の出力、および期待される出力を含めます。issueレポートの統一性は非常に重要です。

古いissueに再現可能な例がない場合は、「Needs Info」としてラベル付けし、例を提供するように依頼します（可能であれば自分で記述します）。すぐに提供されない場合は、issueのクローズの方針に従ってクローズします。

古いプルリクエストの整理#

場合によっては、コントリビューターがプルリクエストを完了できないことがあります。変更をリクエストする最後のレビューからしばらく（たとえば2週間）経過した場合、作業を継続することにまだ関心があるかどうかを丁寧に尋ねてください。さらに2週間ほど返信がない場合は、作業に感謝し、次のいずれかを実行します。

  • プルリクエストをクローズします。

  • pandas-coreのメンバーである場合は、コントリビューターのブランチにプッシュして、作業を完了させます。これは、重要なPRを完了させたり、小さなマージの競合を修正したりするのに役立ちます。

プルリクエストをクローズする場合は、元のissueに「#1234に保留中のPRがあり、役立つ可能性があります。」とコメントし、PRが比較的承認に近づいていた場合は、issueに「Good first issue」のラベルを付けることもできます。

pandasメンテナーになる#

完全なプロセスは、ガバナンスドキュメントに概説されています。要約すると、issueトラッカーで役に立つことで関心を示す人には、誰でもトリアージ権限を与えることを歓迎します。

メンテナーを追加するために必要な手順は次のとおりです。

  1. コントリビューターに連絡し、参加に興味があるかどうかを尋ねます。

  2. 招待を受け入れた場合は、コントリビューターを適切なGitHubチームに追加します。

  • pandas-coreは、コアチームメンバー向けです。

  • pandas-triageは、pandasトリアージメンバー向けです。

pandas-coreに追加する場合は、さらに2つの手順があります。

  1. コントリビューターをpandas Googleグループに追加します。

  2. コントリビューターのGitHubハンドルをpandas-dev/pandas/web/pandas/config.ymlに追加するプルリクエストを作成します。

コアチームメンバーの現在のリストは、pandas-dev/pandasにあります。

プルリクエストのマージ#

プルリクエストをマージできるのは、コアチームメンバーのみです。いくつかのガイドラインがあります。

  1. 通常、承認なしに自分のプルリクエストを自己マージしないでください。例外には、CIを修正するための小さな変更（パッケージバージョンの固定など）が含まれます。変更に非常に自信がある場合は、他のコアチームメンバーの承認を得て自己マージしても問題ありません。

  2. 活発な議論があるプルリクエストや、コアメンテナーからの-1票があるプルリクエストをマージしないでください。pandasは合意によって運営されています。

  3. 大きな変更については、少なくとも2人のコアチームメンバーからの+1があると良いでしょう。

issueのクローズに記載されている項目に加えて、プルリクエストに正しいマイルストーンが割り当てられていることを確認する必要があります。

パッチリリースマイルストーンでマージされたプルリクエストは、通常、ボットによってバックポートされます。ボットがマージに気付いたことを確認してください（通常、1分以内にコメントを残します）。手動バックポートが必要な場合は実行し、手動で実行したら「Needs backport」ラベルを削除してください。タグ付けする前にマイルストーンを割り当てるのを忘れた場合は、次のコマンドでボットにバックポートを要求できます。

@Meeseeksdev backport <branch>

ベンチマークマシン#

チームは現在、pandasのASVパフォーマンスベンチマーク用のウェブサイトをホストするための専用ハードウェアを所有しています。結果は、https://asv-runner.github.io/asv-collection/pandas/に公開されています。

設定#

マシンは、Ansibleプレイブック（tomaugspurger/asv-runner）で設定できます。

公開#

結果は、別のGitHubリポジトリであるtomaugspurger/asv-collectionに公開されます。最後に、ドキュメントサーバーにtomaugspurger/asv-collectionからプルして、/speedから提供するcronジョブがあります。ウェブサーバーへのアクセスについては、TomまたはJorisに問い合わせてください。

デバッグ#

ベンチマークはAirflowによってスケジュールされます。結果を表示およびデバッグするためのダッシュボードがあります。表示するにはSSHトンネルを設定する必要があります。

ssh -L 8080:localhost:8080 pandas@panda.likescandy.com

リリースプロセス#

リリースプロセスでは、特定のバージョン番号を持つユーザーがpandas（gitコミット）のスナップショットを利用できるようにします。リリース後、新しいpandasバージョンは次の場所で利用可能になります。

pandasの新しいバージョンをリリースするプロセスについては、次のセクションで詳しく説明します。

手順には<version>が含まれており、リリースするバージョン（例：1.5.2）に置き換える必要があります。また、リリースするブランチ<branch>は、リリースするバージョンが新しいバージョンのリリース候補であるか、その他のバージョンであるかによって異なります。リリース候補はmainからリリースされますが、その他のバージョンはそれぞれのブランチ（例：1.5.x）からリリースされます。

前提条件#

新しいpandasバージョンをリリースできるようにするには、次の権限が必要です。

  • pandasおよびpandas-feedstockリポジトリへのマージ権限。後者については、conda-forgeレシピに自分のGitHubユーザー名を追加するPRを開きます。

  • pandasリポジトリのmainに新しいタグをプッシュする権限。

  • PyPIへの書き込み権限.

  • ウェブサイト/ドキュメントサーバーへのアクセス。インフラストラクチャ委員会と公開鍵を共有して、メインサーバーユーザーのauthorized_keysファイルに追加してもらいます。

  • お知らせを公開するためのソーシャルメディアアカウントへのアクセス。

リリース前#

  1. 次のトピックについてコアチームと合意します。

    • リリース日（メジャー/マイナーリリースは通常6か月ごと、パッチリリースはx.x.5まで毎月、次のメジャー/マイナーの直前）

    • ブロッカー（リリースに含める必要があるissueとPR）

    • リリースされるバージョンの次のバージョン

  2. リリースするバージョンのリリースノートを更新および整理します。以下を含めます。

    • リリースの最終日を設定します。

    • 未使用の箇条書きを削除します。

    • フォーマットの問題、タイプミスなどがないことを確認します。

  3. リリースするブランチの最後のコミットでCIがグリーンであることを確認します。

  4. リリース候補版でない場合は、リリース対象ブランチへのすべてのバックポートプルリクエストがマージされていることを確認してください。

  5. リリースするバージョンの次のバージョンに対する新しいIssueとマイルストーンを作成します。リリースがリリース候補版だった場合、通常は次のメジャー/マイナーリリースと次のパッチリリースの両方に対してIssueとマイルストーンを作成します。パッチリリースのマイルストーンでは、on-merge: backport to <branch>という説明を追加します。これにより、タグ付けされたPRはボットによって自動的にリリースブランチにバックポートされます。

  6. リリースされるマイルストーンのすべてのIssueとPRのマイルストーンを次のマイルストーンに変更します。

リリース#

  1. リリース対象ブランチの最後のコミットに空のコミットとタグを作成します。

    git checkout <branch>
git pull --ff-only upstream <branch>
git clean -xdf
git commit --allow-empty --author="Pandas Development Team <[email protected]>" -m "RLS: <version>"
git tag -a v<version> -m "Version <version>"  # NOTE that the tag is v1.5.2 with "v" not 1.5.2
git push upstream <branch> --follow-tags

新しいバージョンのドキュメントは、タグがプッシュされたときにトリガーされるCIのドキュメントジョブによって自動的にビルドおよび公開されます。

  1. リリースがリリース候補版の場合のみ、タグを作成した直後に新しいブランチを作成します。たとえば、pandas 1.4.0rc0をリリースする場合、1.4バージョンのコミットをバックポートするために1.4.xブランチを作成します。また、1.5.0の開発開始を示すタグを作成します（次のバージョンであると仮定）。

    git checkout -b 1.4.x
git push upstream 1.4.x
git checkout main
git commit --allow-empty -m "Start 1.5.0"
git tag -a v1.5.0.dev0 -m "DEV: Start 1.5.0"
git push upstream main --follow-tags

  2. wheel staging areaからソースディストリビューションとwheelsをダウンロードします。wheelsが欠落していないことを確認してください（例：ビルドの失敗による）。

    ダウンロードしたいwheels/sdistのバージョンでscripts/download_wheels.shを実行すればうまくいきます。このスクリプトは、pandasのクローン内にdistフォルダを作成し、ダウンロードしたwheelsとsdistをそこに配置します。

    scripts/download_wheels.sh <VERSION>

  3. 新しいGitHubリリースを作成します。

    • タグ：<version>

    • タイトル：Pandas <version>

    • 説明：同じ種類の最新リリース（リリース候補版、メジャー/マイナーまたはパッチリリース）の説明をコピーします。

    • ファイル：生成されたばかりのソースディストリビューション pandas-<version>.tar.gz

    • プレリリースとして設定：リリース候補版の場合のみチェックします。

    • 最新リリースとして設定：古いバージョンのパッチリリースをリリースする場合（例：1.5がリリースされた後に1.4.5をリリースする場合）を除き、チェックしたままにします。

  4. PyPIにwheelsをアップロードします。

    twine upload pandas/dist/pandas-<version>*.{whl,tar.gz} --skip-existing

  5. GitHubリリースは、数時間後に自動化されたconda-forge PRをトリガーします。（待つ必要がない場合は、@conda-forge-admin, please update versionというタイトルのIssueを開いて、ボットをトリガーできます。）CIがグリーンになったらマージすると、conda-forgeパッケージが生成されます。

    手動でPRを行う必要がある場合、通常はバージョン、sha256、およびbuildフィールドを変更する必要があります。レシピで前回リリース以降に変更があった場合、それらの変更はci/meta.yamlで確認できます。

リリース後#

  1. Webサーバーにログインし、/var/www/html/pandas-docs/stableを編集して、メジャーおよびマイナーリリースではversion/<latest-version>を指すように、パッチリリースではversion/<minor>をversion/<patch>を指すようにして、安定版ドキュメントへのシンボリックリンクを更新します。正確な手順は次のとおりです（例のバージョン番号は、リリースするバージョンに適した番号に置き換えてください）。

    • サーバーにログインし、正しいユーザーを使用します。

    • cd /var/www/html/pandas-docs/

    • ln -sfn version/2.1 stable （メジャーまたはマイナーリリースの場合）

    • ln -sfn version/2.0.3 version/2.0 （パッチリリースの場合）

  2. メジャーまたはマイナーリリースをリリースする場合は、ソースコードにPRを開いて、ドキュメントドロップダウンメニューに必要なバージョンが含まれるようにweb/pandas/versions.jsonを更新します。

  3. リリースされたバージョンのマイルストーンとIssueを閉じます。

  4. 次のリリースの新しいIssueを、推定リリース日とともに作成します。

  5. 次のバージョンのリリースノートのプレースホルダーを使用してPRを開きます。たとえば、1.5.3のPRを参照してください。使用するテンプレートは、メジャー、マイナー、パッチリリースのいずれであるかによって異なることに注意してください。

  6. 公式チャネルで新しいリリースを発表します（以前の発表を参照に使用します）。

    • pandas-devおよびpydataメーリングリスト

    • Twitter、Mastodon、Telegram、LinkedIn

  7. このリリース手順を更新して、不正確な点を修正し、前回のリリース以降の変更について更新します。