Zenn
👻

PyTorchにコントリビュートしてみた

2023/08/24に公開
PyTorch
オープンソース開発
tech

概要

先日torch.optim.RAdamに機能追加のPR[1]を送ったので、PyTorchリポジトリにコントリビュートするさいのフローや気をつけるべき点についてまとめておきたいと思います。

これを読むことで雰囲気を知ってもらい、オープンソースのリポジトリにコントリビュートすることについての敷居が少しでも下がれば良いかな、という意図で書きます。

なお、手順は執筆時点(2023/8/24)のもので将来的に変更される可能性があります。実際に作業を行う際はPyTorch最新のガイドラインや手順を参照してください。

大まかな流れ

  1. Issueを投げて修正方針について議論する
  2. 修正方針が決まったらPRを作る
    • 環境構築
    • 必要な資材
      • コード
      • テストコード
      • ドキュメント
  3. PRをレビュアーにアサインしてもらう
  4. PRがFixしたらマージしてもらう

基本的な流れはGitHubによる一般的な開発フローと大差がないので、以下では特筆すべき部分に絞って書きます。

環境構築

まずはコントリビューター向けのガイドライン[2]にざっと目を通します。
と言っても、全部目を通すのは大変なので、最低限必要な部分をまず確認すると良いと良いと思います。

  • 開発環境構築（ソースからのインストール）
  • ローカルでの単体テストの実行方法
  • ドキュメントの自動生成&プレビュー方法

ソースからのインストール

PyTorchのリポジトリのREADMEにある"From Source"の項目[3]を参考に構築していきます。
最初は「Docker環境でワンコマンドで構築できるのかな？」と思ってたのですが、開発者向けのDocker imageなどは特に公式には用意されていないようでした。
自分は最低限必要な資材を自前のDockerfileで構築[4]し、masterブランチの内容によって変動しうる部分のみ手動で作業する方針にしました（それでもまだ手動のコマンド入力が多いので、もう少し改善の余地はあると思います）。

HTMLドキュメントの確認方法

自分はリモートサーバ上でコンテナを起動して開発しているので、生成されたHTML形式のドキュメントをローカルから確認するには以下の作業が必要でした。

  1. 8000番ポートを開ける(docker-compose.ymlに実装ずみ)
  2. コンテナ内から簡易サーバを起動
    cd pytorch/docs
python -m http.server 8000 --directory build/html
  3. ローカルからサーバにポートフォワーディング
    ssh -L 8000:localhost:8000 remote-machine
  4. ローカルPCのブラウザからドキュメントを確認http://localhost:8000

コントリビューター向けライセンス契約のサイン

コントリビューター向けのライセンス承諾(CLA)[5]にサインする必要があるようです。
こちらは特に求められたわけではないですが、自分の場合はどうせ必要だろうと思ったので自発的にサインしました（本来はコミッター側の誰かに必要かどうか確認すべきだと思います）。
Contributing Guidelines[6]に契約が必要である旨が明記されていました（このドキュメントの存在気づいてなかった...）。

所感・学び

今回のPR発行で課題に感じたことや学びについて以下に述べます。

ローカルでの動作確認をきっちりと行う必要がある

今回optimizerの1つに機能追加を行いましたが、既存で実装されているのは「一定のstep後にlossが減っているか？」と言った基本的なもののみで、「追加した機能が元の機能を壊していないか？」「追加したロジックは妥当か？」という観点でのテストコードは実装されていないようでした。実装コードの妥当性についてはテストコードに頼れないので、自分でローカルで動かしてみて実装した部分が正しく動いているかどうかを確認する必要がありました（具体的にはweightのL2ノルムをprint出力して「weightがちゃんとdecayしているか？」を目視で確認したりしていました）。

また、レビュアーもロジックの細部まできっちり見てくれるとは限らないと感じました。Issueの優先度が「triage」という比較的低いタグが付けられたためか、アーキテクト的なポジション（と思われる）の方のレビューのみでした。そもそも人間のレビュアーが検知できるバグには限界があります。極論を言うと、「機能で何か問題が生じたら全て自分の責任」くらいの気持ちでPRを出す方が無難かもしれません（結果的に敷居は上がってしまいますが...）。

特にレビューして欲しい内容はdescriptionに記載しておく

これはPyTorchに限らず、一般的なGitHubによる開発の作法だと思います。
自分の場合はネイティブ話者でないのでドキュメントの文章に自信がなかったのですが、最初何も書かずにコミットしていたらそのままマージされてしまいそうになりました。
後に「私はネイティブでないので文章がまともかどうかをレビュアーに確認して欲しい」という旨のコメントを書いたら文章を校正していただけました。
こういった懸念点があるなら最初から書いておく方が手戻りがなくて良いと思います。

ドキュメントは視覚的な結果も含めて共有する

Docstringについて、コード上だけでの確認だと「レイアウト崩れ」などの視覚的な問題や「リンクが壊れている」と言ったHTMLの機能的な問題に気づきづらくなります。
今回やり取りした感じだとレビュアー側で毎回必ずその辺りを確認しているようでもなかったので、ドキュメントを変更した場合は最終生成結果も合わせて共有した方が無難かもしれません（尤も、PDFとソースの不整合が生じる可能性があるので、レビュアー側でHTMLを生成して確認してもらうのが確実ですが）。

ChatGPTが役立った

込み入った議論になってくると「日本語だと表現できるけど英語でなんと言ったら相手に伝わるかわからない」ような場面が何度かありました。こちらの意図を相手に正確に伝えるためにChatGPT-4(有料版)で下訳を作ってもらうとかなりの作業時間が軽減されました。また、ドキュメンテーションの文章の下訳作りにも有効でした。

結び: コミットした背景

今回、たまたまPyTorchにコントリビュートする機会があったので体験記的なものを書きました。
最後に、今回コントリビュートすることにした意図と背景について説明しておきます。
私自身はそこまで頻繁にオープンソースへのコミットを行っているわけではないですが、たまに「勉強の」意味でコミットすることがあります。今回は以下のような意図と背景がありました。

意図

  • 割と利用者も多くプロジェクトの規模もそこそこ大きめなプロダクトでリポジトリの管理がどのように行われているか知っておきたかった
  • プロジェクト全体のテスト実装、およびOptimizerのテスト実装のベストプラクティスを知りたかった

背景

  • 同様の変更を行なったPRがすでにあったので参入しやすかった

感想として、ユーザが多く影響も大きいプロジェクトなので、「もしバグを仕込んでいたら...」と考えると細部まで神経を使いました。とはいえ、一旦流れを一通り体験しておけば、今後もっと自分にとって優先度の高い変更をコミットしたくなった場合の敷居も下がるかな、と思いました。他の人にとっても役立つ内容であれば幸いです。

参考資料

GitHubで編集を提案

Discussion