本投稿は、Quick OSS Contribution Guide - How to start contributing to open source with PyTorch Lightning の翻訳です。一部、内容に変更があります。
0. はじめに
PyTorch Lightning は、世界中の研究所や企業の研究者、機械学習エンジニア、学生等により支えられているオープンソースの深層学習フレームワークです。PyTorch Lightning に貢献していただけた方に向けて、無料の Lightning SWAG を用意しています!
OSS への貢献に興味があるものの、どこから始めればいいかわからない方のために、本投稿では PyTorch Lightning への貢献方法を解説します。
-
まず、コントリビューションガイドラインを読んで、Lightning の設計方針や良い貢献とはなにかを確認してください。
-
Git を使ったことがない方は、他のウェブサイトや本投稿に記載の例を参考にして、変更したコードの記録や他のユーザが書いたコードを取り入れる方法等を確認してください。翻訳者のおすすめはシステム開発プロジェクト応用第一 第5,6回 Gitによるバージョン管理です。
-
取り組む貢献内容を GitHub issue から選んでください。"good first issue" というラベルがついた issue は初心者の方でも取り組みやすい内容です。取り組む issue を決めた後は、その issue にその旨を書いていただければ、メンテナがその issue をあなたにアサインします!
わからなくなった場合は GitHub Discussions もしくは Slack にてお気軽にご質問ください。
:GitHub Discussions: https://github.com/PyTorchLightning/pytorch-lightning/discussions/
PyTorch Lightning Slack: https://join.slack.com/t/pytorch-lightning/shared_invite/zt-pw5v393p-qRaDgEk24~EjiZNBpSQFgQ
1. 開発環境を準備する
このセクションでは、貢献活動に必要な開発環境を整えます。
-
レポジトリをフォークします。参考: プロジェクトに貢献する - GitHub Docs
-
フォークしたレポジトリをローカルに (もしくは、Grid session に) クローンし、”upstream” が公式レポジトリを指すように設定し、確認します。HTTPS、SSH、GitHub CLI の好きな方法で、フォークしたレポジトリをクローンしてください。
以下の操作例を参考にしてください。$ git clone https://github.com/<ユーザネーム>/pytorch-lightning.git # フォークしたレポジトリをクローンする Cloning into 'pytorch-lightning'... ... $ cd pytorch-lightning # プロジェクトディレクトリに移動 $ git remote add upstream https://github.com/PyTorchLightning/pytorch-lightning.git # upstream が公式レポジトリを指すように設定 $ git remote -v # upstream が公式レポジトリを指していることを確認 origin git@github.com:<ユーザネーム>/pytorch-lightning.git (fetch) origin git@github.com:<ユーザネーム>/pytorch-lightning.git (push) upstream git@github.com:PyTorchLightning/pytorch-lightning.git (fetch) upstream git@github.com:PyTorchLightning/pytorch-lightning.git (push) $ git fetch --all --prune ... -
過去に PyTorch Lightning に貢献したことがある場合、それ以降に多くのコードが変更されていることがあるため、フォークしたレポジトリの master ブランチに upstream から変更を受け入れて最新の状態にしておくことをおすすめします。
次のセクションでは、実際にコードに変更を加え始めます。
その前に、常にコードが最新の状態であることを確認しておきましょう。
VS Code のような IDE で Git の操作をする方が多いと思いますが、CLI で操作をする方のために、便利なコマンドを紹介します。
$ git fetch --all --prune # リモートの更新をすべてダウンロードする
$ git checkout master # メインブランチにチェックアウトする
$ git merge upstream/master # 公式レポジトリの変更を適用し最新の状態にする
$ git push # 最新の状態を自分のフォークレポジトリに push する
1. 実装に取り組む
ここまでで、開発環境が整い、Git の使い方を確認し、取り組む issue を決めました。
ここからは、実際に実装に取り組みましょう。手順は次のとおりです。
- 変更を加えるための新たなブランチを作成します。
-
推奨されるブランチ名は
<type>/<issue-id>_<short-name>です。- ここで
<type>は具体的にbugfixfeaturedocstests等を指します。 - ドキュメントの変更は基本的に事前に issue を立てる必要がないため
<issue-id>は必要ありません。
- ここで
- ブランチ名の例
bugfix/12345_ddp-syncdocs/fix-typo-callback
-
推奨されるブランチ名は
- バグ修正の場合、まず、テストケースを書いてからそのバグを修正することを勧めます。
- そのバグの影響で新たに作成したテストケースが通らないことを確認後、そのテストが通るまでそのバグ修正を試みます。
- もし修正方法がわからない場合、テストケースを含んだ PR を提出していただけるだけでも正当な貢献です! PR を出していただければ、メンテナが一緒に解決します。
- 変更を終えた後、その変更を簡単な説明とともに commit します。
- 新たに作成したテストが通ることを確認して、その変更をフォークレポジトリに push します。
以下の例を参考にして、これまでの操作を行ってください。
$ git checkout -b MY_BRANCH # master ブランチから新しいブランチを作成する
$ ... # コードを修正する
$ git add pytorch_lightning/my_new_file # commit するファイルを選ぶ
$ git commit -m "変更内容を簡単に説明" # 加えた変更を commit する
$ git push origin MY_BRANCH # commit をリモートに push する
2. 自身の PR を提出する
ここまでで、ローカル環境での開発が無事に終わりました。最後に、PR (pull request) を提出しましょう。
複数の GPU や異なる OS 等でのテストを自身の環境で実行できない場合は、ドラフト PR を作成してください。変更を push するたびに自動的に各種テストを実行することができます。
リモートに変更を push すると、フォークしたレポジトリの GitHub ページに “Compare & Pull Request” というボタンが表示されます。
上記のボタンを押して PR を作成する画面にいきます。
PR の内容を簡潔に説明するタイトルをつけ、その PR テンプレートにしたがって詳細を記入します。
PR の目的や変更内容の説明を記入し、
- 準備が整っている場合は ”Create pull request” で PR を作成し、
- メンテナと相談したいなどまだレビューを受ける準備ができていない場合は “Create draft pull request” でドラフト PR を作成してください。
PR を作成する際、もしくは作成した後にチェックリストを確認し、チェックを加えてください。
ここですべてのテストが通過していることを確認してください。
もしテストが通っていない場合は、該当するテストのところをクリックしてエラーを確認し、必要な修正を加えてください。
提出された PR がマージされるには、3 名のコアメンバーからのレビューを受ける必要があります。レビュワーは変更内容を確認し、質問をしたり、提案をする場合があります。一度きりのレビューだけでは終わらずに、複数回のやり取りが発生する場合もあります。これらのフィードバックから PyTorch Lightning やコーディングのベストプラクティスをもっと知ることができるでしょう。
以上です! もしわからないことがあれば、GitHub Discussions もしくは Slack にてお気軽に質問してください。
-1. おわりに
著者
Jirka Borovec は複数の IT 企業で機械学習とデータサイエンスの業務に携わっています。特に、実世界の問題を state-of-the-art の技術で解決することに興味があります。また、これまで複数の Python オープンソースプロジェクトの開発に携わり、現在もよく知られるプロジェクトで活動をしています。
翻訳者
日本の田舎で学生をしています、Akihiro Nitta です。貢献する前に心配なこと等あれば、Twitter にて DM していただければベストエフォートでお手伝いします。お気軽にご相談ください :)