6.2 GitHub - プロジェクトへの貢献

自分のArduino上で実行するコードを探していたトニーは、GitHub 上にすばらしいプログラムがあることを発見しました。 それが https://github.com/schacon/blink です。

ただ、ひとつ問題がありました。点滅の間隔が速すぎるのです。1 秒おきに状態を切り替えるのではなく、3 秒くらいは間を置きたいものです。 さて、このプログラムを改良して、その変更を提案してみましょう。

まずは、先ほど説明した Fork ボタンをクリックして、このプロジェクトのコピーを手に入れます。 この例で使うユーザー名は “tonychacon” とします。つまり、できあがったコピーは https://github.com/tonychacon/blink となり、ここからはこのプロジェクトを変更していきます。 これをローカルにクローンして、トピックブランチを作り、コードを変更して、その変更を GitHub にプッシュしましょう。

この状態で GitHub 上のフォークに戻ると、GitHub 上に新しいトピックブランチがプッシュされたことを伝えてくれます。 また、大きな緑色のボタンを使えば、変更点を確認したり、元のプロジェクトへのプルリクエストを送ったりできます。

あるいは、https://github.com/<user>/<project>/branches にある “Branches” ページから自分のトピックブランチに移動して、そこからプルリクエストを送ることもできます。

この緑のボタンをクリックすると、プルリクエストのタイトルと説明を入力する画面に遷移します。 ちゃんと時間をかけて説明を書きましょう。損はしないはずです。プルリクエストを受ける側のプロジェクトオーナーからすれば、説明文がよければあなたの意図が汲み取りやすくなるからです。そうすれば、オーナーはプルリクエストの内容を正確に評価できますし、それを取り込むことがプロジェクトにとってプラスかどうかを判断できるでしょう。

この画面では、トピックブランチ内のコミットのうち、`master`よりも先行しているコミットの一覧 (今回の場合はひとつだけ) も確認できます。 また、このブランチをオーナーがマージしたときに適用される変更の、unified形式の差分も表示されます。

この画面で Create pull request ボタンを押すと、フォーク元のプロジェクトのオーナーに、 誰かが変更を提案しているという通知が届きます。この通知には、変更に関するすべての情報が記載されたページへのリンクが含まれています。

これで、元のプロジェクトのオーナーは、変更の提案を見られるようになりました。それをマージしたり、却下したり、コメントしたりすることができます。 ここでは、オーナーが変更提案を気に入ったものの、ライトが消えている時間を点灯している時間よりも少しだけ長くしたほうがいいと感じたことにしましょう。

[ch05-distributed-git] のワークフローなら、この手のやりとりはメールで行うところですが、GitHub の場合はこれをオンラインで行います。 プロジェクトのオーナーはunfied diffをレビューして、コメントを残します。コメントしたい行をクリックすれば、コメントを残せます。

メンテナがコメントを入れると、プルリクエストの作者 (そして、そのリポジトリをウォッチしているすべての人たち) に、通知が届きます。 通知をカスタマイズする方法については後述しますが、メールでの通知を受け取るように設定している場合は、以下のようなメールも届きます。

オーナーだけでなく誰でも、プルリクエスト全体に対するコメントができます。 プルリクエストのディスカッションページ では、プロジェクトのオーナーがコードの特定の行についてコメントしたうえで、さらにプルリクエスト全体に関するコメントも残しています。 また、コードへのコメントが、一連の会話に組み込まれていることにもお気づきでしょう。

プルリクエストの作者は、自分の変更を受け入れてもらうために何が必要なのかがわかりました。 幸運にも、そんなに手間のかかることではありません。 メールでのやりとりの場合は、一連の作業をやり直した上でもう一度メーリングリストに投稿する必要がありますが、 GitHub なら、単にトピックブランチにコミットしてそれをプッシュするだけで済みます。 また、プルリクエストの最終形 にあるように、更新されたプルリクエストでは変更前のコードへのコメント表示が省略されています。追加されたコミットによって変更されたコードへのコメントだからです。

なお、既存のプルリクエストにコミットを追加しても、通知は送られません。そこで、修正をプッシュしたトニーは、修正が終わったことをコメントでプロジェクトオーナーに伝えることにしました。

このプルリクエストのページで “Files Changed” タブをクリックすると、“unified” 形式の diff を確認できます。 つまり、このトピックブランチをマージしたときにどんな変更が施されるのかを、まとめて確認できるのです。 git diff の用語に直すと、このタブを開いたときに表示される内容は、プルリクエストの対象になっているブランチ上で git diff master...<branch> を実行した結果になります。 この形式の diff についての詳細は、何が変わるのかの把握 を参照ください。

もうひとつお気づきのことがあることでしょう。 GitHub は、このプルリクエストが問題なくマージできることを確認したうえで、サーバー上でマージを実行するためのボタンを表示します。 このボタンが表示されるのは、あなたがこのリポジトリへの書き込みアクセス権限を持っていて、かつ問題なくマージ可能な場合だけです。 このボタンをクリックすると、GitHub は “non-fast-forward” なマージを行います。 つまり、仮に fast-forward 可能なマージであったとしても、明示的にマージコミットを作ります。

お望みなら、このブランチを取得した上で、ローカルでマージすることもできます。 このブランチを master にマージしてから GitHub にプッシュすると、このプルリクエストは自動的に閉じられます。

これが、大半の GitHub プロジェクトが使っている基本的なワークフローです。 トピックブランチを作り、そこからプルリクエストを作って、議論を重ね、必要に応じてさらに作業を重ねて、最終的にそのリクエストをマージするか、あるいはマージせずに終了します。

実際のところ、多くのプロジェクトは、プルリクエストを完璧なパッチ群である (つまり、きちんと順序どおりに適用しなければいけない) とは考えていません。 これは、メーリングリストベースで運営するプロジェクトで一般的な考えかたとは異なります。 GitHub のプロジェクトでは、プルリクエストのブランチを変更提案に関する議論の場と捕らえていることが多く、 最終的にできあがった unified diff をマージするのだと考えています。

この違いを認識しておくことが大切です。一般に、変更を提案するのは、コードが完璧に仕上がる前の段階です。 一方、メーリングリストベースの運営では、まだできあがってもいないパッチを投稿することなど、まずないでしょう。 未完成の段階で変更を提案することで、メンテナとの議論を早めに始めることができます。 コミュニティの協力で、より適切なソリューションにたどり着けるようになるでしょう。 プルリクエストで提案したコードに対してメンテナやコミュニティから変更の提案があったときに、 パッチをゼロから作り直す必要はありません。 差分だけを、新たなコミットとしてプッシュすればいいのです。 その後の議論は、これまでの経緯を踏まえた上で進みます。

プルリクエストの最終形 をもう一度見てみましょう。プルリクエストの作者は、自分のコミットをリベースして新たなプルリクエストを作ったわけではありません。 単に、新しいコミットを追加して、それを既存のブランチにプッシュしただけです。 そのおかげで、今後このプルリクエストのページを見直すことがあったときにも、最終的な決定に至るまでの経緯を簡単に確認できるのです。 “Merge” ボタンを押したときに、本来不要な場面でも意図的にマージコミットを作っているのは、 後からそのプルリクエストを参照しやすいようにするためです。 必要に応じて、それまでの流れをすぐに調べることができます。

プルリクエストを作った後で元のプロジェクトに変更が加わったなどの理由で、プルリクエストがそのままではマージできなくなることがあります。 そんな場合は、そのプルリクエストを修正して、メンテナがマージしやすいようにしておきたいことでしょう。 GitHub は、そのままでマージできるかどうかをチェックして、すべてのプルリクエストのページの最下部に結果を表示します。

そのままではマージできないプルリクエスト のようになっていたら、自分のブランチを修正して、この表示がグリーンになるようにしたいところです。 そうすれば、メンテナに余計な手間をかけさせずに済みます。

グリーンにするための主な選択肢は、二種類あります。 ひとつは、自分のブランチを、プルリクエストの対象ブランチ (普通は、フォーク元のリポジトリの master) の先端にリベースすること。 もうひとつは、その対象ブランチを自分のブランチにマージすることです。

GitHub 上の開発者の多くは、後者を選んでいるようです。その理由は、先述したとおりです。 重要なのは、そこにいたるまでの歴史と、最終的にマージしたという事実だと考えているのでしょう。 リベースをすると、歴史がすっきりするという以外の利点はありません。そして、リベースはマージに比べて ずっと 難しいし、間違いを起こしやすいものです。

対象ブランチをマージして、自分のプルリクエストをそのまま取り込んでもらえるようにする手順は、次のとおりです。 まず、オリジナルのリポジトリを新しいリモートとして追加して、それをフェッチします。 そして、そのリポジトリのメインブランチを自分のトピックブランチにマージします。 何か問題があれば修正し、その結果をプルリクエストと同じブランチにプッシュします。

先ほどの “tonychacon” の例に戻りましょう。プルリクエストを出した後にオリジナルの作者がリポジトリに変更を加えたため、 プルリクエストがそのままでは取り込めなくなってしまいました。そんな場合の手順は、以下のとおりです。

これでプルリクエストが自動的に更新されて、マージ可能かどうかが再びチェックされます。

Git のすばらしいところのひとつが、これらの作業を継続的に行えるということです。 長期にわたるプロジェクトでも、対象ブランチからのマージを何度でも繰り返せるので、前回のマージ以降に発生した衝突さえ気をつけていれば、混乱なく作業を続けられます。

ブランチをリベースしてすっきりさせたい場合は、そうしてもかまいません。 しかし、既に作成済みのプルリクエストに対して、それを強制的にプッシュするのは避けたほうがいいでしょう。 もし他の人がそれを手元に取得して何かの作業を進めると、ほんとうは怖いリベース で説明したような問題が発生します。 リベースした場合は、それを GitHub 上で新しいブランチにして、新しいプルリクエストを作るようにしましょう。 新しいプルリクエストから元のプルリクエストを参照して、そして元のプルリクエストは閉じてしまいます。

…と言われて気になるのは、「元のプルリクエストをどうやって参照すればいいの？」ということでしょう。 GitHub 上で他のものを参照するにはいろんな方法があって、GitHub 上で何かを書ける場所ならほぼどこでも他のものを参照できます。

まずは、別のプルリクエストあるいは Issue を相互参照する方法から紹介します。 プルリクエストや Issue には番号が振られていて、この番号はプロジェクト内で一意になっています。 つまり、たとえばプルリクエスト#3とIssue #3が 両方とも 存在することはありえないのです。 他のプルリクエストや Issue を参照したい場合は、コメントや説明文の中で単に #<num> と書くだけでかまいません。 あるいは、もう少し細かく、誰か他の人が作った Issue やプルリクエストを指定することもできます。 username#<num> と書けば、今いるリポジトリの別のフォーク上での Issue やプルリクエストを参照できるし、 username/repo#<num> と書けば、別のリポジトリ上のものも参照できます。

実例を見てみましょう。 先ほど説明したとおり、リベースをした上で新しいプルリクエストを作ったものとします。新しいプルリクエストから、古いプルリクエストを参照したいところです。 また、そのリポジトリのフォーク上にある Issue や、まったく別のプロジェクトにある Issue も参照するつもりです。 説明文は、プルリクエスト内での相互参照 のようになります。

このプルリクエストを投稿すると、画面上では プルリクエスト内での相互参照のレンダリング のような表示になります。

GitHub の完全な URL を入力したところも、画面上では短縮されて、必要な情報だけが見えていることがわかるでしょう。

トニーが元のプルリクエストを閉じると、そのことが新しいプルリクエストのほうにも表示されることがわかります。 GitHub が、プルリクエストのタイムラインに自動的にトラックバックを送ったのです。 これで、古いプルリクエストを見にきたすべての人は、そのリクエストの後継となる新しいプルリクエストにたどり着けるようになるのです。 リンクは、プルリクエスト内での相互参照のレンダリング のように表示されます。

issue の番号だけでなく、SHA-1 を示して特定のコミットを参照することもできます。 SHA-1 を指定する際には 40 文字ぶんすべてを示す必要がありますが、コメントの中に SHA-1 を発見すると、GitHub はそれを当該コミットへリンクしてくれます。 他のフォークやその他のリポジトリのコミットを参照する場合の方法は、issue の場合と同じです。

GitHub Flavored Markdownは、基本的なMarkdownの文法に、GitHub 流の味付けをしたものです。 プルリクエストや Issue を作ったり、それにコメントしたりするときに、役立つことでしょう。