TL;DR
OSS開発をしてみたいと思っているのために、どういう手順でコントリビュートをすればいいかを解説します。
OSSの探し方については言及しません。
OSSの探し方についても、冒頭で少しだけ言及します。(2022/02/06 追記)
OSSの探し方
自分が普段使っているライブラリやフレームワークがGithubリポジトリで公開されているかどうか調べてみるといいでしょう。
そして見つけたOSSへの貢献方法ですが、モノによっては「good first issue」という初心者が取り組みやすい課題をまとめてくれているコミュニティもあります。
こちらから探してみるとよいでしょう。
全体の流れ
OSS開発の流れとしては、
- 本家OSSリポジトリをForkし、自分のリポジトリにクローンを作成
- 自分のリポジトリに作成したクローンを再びローカルにクローン
- 本家リポジトリのURLをUpstreamとして登録する
- 実行環境を作成
- アプリケーションを実行し、気になったところについて本家OSSリポジトリにIssueを作成し、オーナーのレビューを受ける
- 自らの出したIssueに対してオーナーから修正の許可が出たら修正を始める
- ローカルにクローンしたプロジェクトから修正用ブランチを切り、修正を加える。
- 修正が終わったら、自分のリポジトリにpush
- githubの自分のリポジトリから、OSS本家のリポジトリに対してpull requestを送信する
- pull requestがマージされたら見事コントリビュート成功！
- pull requestがマージされたら、Issueをcloseする
という流れになることが多いかと思います。
細かい話をすれば、テストコードの有無といった書くOSSごとの開発ルールがあったりするのですが、
そのOSS独自のコントリビュートのルールというのは基本的に「README」もしくは「CONTRIBUTE」という名前のマークダウンに書かれています。
なので、自身がコントリビュートしようとしているOSSのREADMEなどには一通り目を通しておくとよいでしょう。
それでは以降で各工程について解説をしていきます。
OSSのリポジトリをForkする
OSSに対してコントリビュートするためには、兎にも角にもソースコードと実行環境がなければ始まりません。
というわけで、まずは本家OSSのソースコードを持ってくるところから始めましょう。
これは本家OSSのリポジトリをForkすることで可能となります。
Forkは以下の画像のとおり、リポジトリのForkボタンを押下することで可能です。
Forkを行うと、本家のOSSリポジトリのクローンが自分のリポジトリに作成されます。
あとは自分のリポジトリに作成されたクローンに対して修正を加えていくことになります。
自分のリポジトリに作成したクローンを再びローカルにクローン
これは例の如く、ローカルでgit cloneするだけです。
一応やり方を載せておきます。
clone用のURLを確認。
以下のhttps://の部分を上で確認したURLに置き換えて実行するだけです。
実行の際はプロジェクトを作るディレクトリに移動してから行います。
git clone https://github.com/xxxx/本家リポジトリのURLをUpstreamとして登録する
git remote add upstream https://github.com/本家リポジトリのURL本家リポジトリのURLは本家リポジトリの画面上で、2と同じ手順で確認します。
実行環境の作成
これはOSSのREADMEに書いていることが多いです。
READMEの内容に従って環境を作成しましょう。
その際に困ったことがあれば、本家OSSリポジトリのIssueから質問してみましょう。
OSSオーナーや、他のコントリビューターが助けてくれると思います。
アプリケーションを実行し、気になったところについて本家OSSリポジトリにIssueを作成し、オーナーのレビューを受ける
実行環境ができてアプリケーションの動作を確認できたら、自分がコントリビュートするべき内容を探していきましょう。
アプリケーションを実際に使ってみたり、あるいはソースコードを読んでみると良いかと思います。
- 画面や機能でイケてないところ
- そもそもバグっているところ
- コードのイケていないところ
- 最低限のお作法が守れていないコード
- メールサーバーやコンテナの中身が古いので新しいものに変更する
このあたりを意識しながら見ていくと、コントリビュートする内容が見つかるかと思います。
初心者のうちはハードルが高いような気がしますが、READMEのドキュメントを修正するだけでもコントリビュートになります。
なので、「このOSSプロジェクトに対して自分が貢献できることはなにか？」を考えることが重要だと思っています。
さて、コントリビュートしたい内容が決まれば、OSSオーナーにIssueを出します。
このIssueの内容で気をつけるべきことは以下の通りです。
- 何はともあれTL;DR。このIssueで何を伝えたいのかをまず最初に書く
- 実際の画面やコードを添付して、どの機能・コードのことを言っているのかを明確にする
- Actual(現状)とWant to(こうしたい)を明確にする
- 最後にまとめを書く
さらに実際に私が出したIssueを参考にしながら、いくつか追加でやると良さそうなことを書いておきます。
コードの話をするのであれば、当該コードを含める
コードの話をするのであれば実際のコードを引用してきましょう。
引用の仕方は簡単で、githubのリポジトリ上で引用したい箇所の始まりをクリック。
それから、引用したい箇所の最後の行をshift+クリック
その後、Preferrence in new issueを選択することで当該コード範囲についてissueを起こすことができます。
また、既存のissueにコードの参照を追加したり、複数の該当箇所を含めたり、pull requestへ参照を含めたい場合は、Copy permalinkを選択します。
その後、issueやpull requestのテキストに貼り付けを行うとコードスニペットが貼り付けできます。
こんな感じ。
画面の話をするのであれば、当該画面を含める
画面や機能の話をするのであれば、その画面や一連の動作がわかるような画面キャプチャを貼り付けましょう。
また、実態と修正後のイメージが対比できるように画像を用意するとなお良いでしょう。
自らの出したIssueに対してオーナーから修正の許可が出たら修正を始める
さて、issueを出したらOSSのオーナーが内容を確認してくれるまで待ちましょう。
往々にしてアメリカ、イギリス等に在住なことが多いので返事がくるまでには最速でも半日ほどかかります。
ここでOSSのオーナーからくる返事のパターンとしては、
- OK,issueの内容で修正していってみて
- いや、その修正は必要ないよ
- ここがよくわからない。詳しく説明してくれ
の3つに大体分類されます。
1のときは特に何もありません。
開発に入っていきましょう。
2の場合は残念ですが、issueはcloseです。
次の開発の種を探しましょう。
3の場合は追加で説明を加えましょう。
3が来る場合は説明が不十分かもしれません。
より詳しく画像や別途作図ツールを使って、説明を補足しましょう。
ローカルにクローンしたプロジェクトから修正用ブランチを切り、修正を加える。
ここでは特に言及することはありません。
開発のマナー上普通のことだと思います。
一応、VSCodeでブランチを切る方法を記載しておきます。
コマンドの場合はこう。
git checkout 作成元のブランチ
git checkout -b 作成するブランチ名修正が終わったら、自分のリポジトリにpush
普通にリモートにpushしてください。
ただし、大体のOSSではテストコードが含まれています。
基本的にプルリクを送信した際に自動テストが走りますが、この時点でテストコードがエラーを吐いているととても恥ずかしい上、テストコードを実行していない不束者と見做されてしまうでしょう。
そうなると、とても印象が悪いです。
これもOSS開発に限った話ではなく、どの開発の現場でも当たり前なことですが実装の途中、そして実装が終わった後にはテストを実行して自らのコードが既存のコードを破壊していないことを確認しましょう。
あくまで自動テストは最後の砦です。
githubの自分のリポジトリから、OSS本家のリポジトリに対してpull requestを送信する
自分のリポジトリからpull requestを作成します。
するとマージ先と元を選択できるので、相手のリポジトリのmainブランチに対して、8で修正した自分のリポジトリのブランチを選択します。
以下の赤丸の部分をmainから変更します。
プルリクを作成するにあたって気をつけるべき点は以下の2点です。
- issueの番号を含める
- 画面の修正を行なった場合、修正前後のイメージを添付する
- 機能の修正を行なった場合、修正の前後の違いを記載する
こちらも実際のプルリクの内容を参考にしてもらうといいでしょう。
以下、特記事項です。
プルリクにissueの番号を含める
これにより、レビュイーは「このプルリクはどのissueに対するものなのか？」を把握できます。
issueは #issue番号 とすることで自動的にリンクされます。
ちなみにissueの番号はissueの画面のここに記載されています。
pull requestがマージされたら見事コントリビュート成功！
見事マージされたら、おめでとう！これであなたもOSSコントリビューターです。
喜ぶのはほどほどに、さっそく本家OSSリポジトリのmasterブランチにマージされた内容を、自分のmasterブランチに反映させましょう。
以下の手順で行います。
git checkout master
git fetch upstream
git merge upstream/master --ff-only
git push origin master -uこれで自分のmasterブランチに、9でマージされた内容が取り込まれるはず。
OSSコントリビュートできた実感が一番湧く瞬間ですね！
pull requestがマージされたら、Issueをcloseする
後始末ですね。
修正が完了したissueをクローズして、対応を終わりにしましょう。
そして、また次のissueを作るのです。
おわりに
今回はOSSコントリビュートのサイクルと詳細な手順について解説しました。
他の記事を見ていると、issueの書き方やプルリクの書き方などに触れているところがなかったので、開発初心者だと困るだろうなと思っていました。
OSSにコントリビュートすることは、貴重な手を動かす機会になります。
OSSのモノによりますが、初心者ほどOSSへコントリビュートすることで他人のコードから学びを得たり、普段関わらない人間の目線でのレビューを受けることができ、上達へとつながると考えています。
この記事を参考にOSSコントリビューターが増えてくれたら嬉しいです。
