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

Tonyは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ブランチよりも「進んでいる」もの（この場合は1つだけ）のリストと、このブランチがプロジェクトオーナーによってマージされた場合に適用されるすべての変更の統合差分も表示されます。

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

この時点で、プロジェクトオーナーは提案された変更を見て、マージするか、拒否するか、コメントすることができます。彼がそのアイデアを気に入ったが、ライトが点灯している時間よりも消灯している時間を少し長くしたいとしましょう。

分散Gitで示されているワークフローではこの会話がメールで行われる可能性がありますが、GitHubではこれがオンラインで行われます。プロジェクトオーナーは統合差分を確認し、任意の行をクリックしてコメントを残すことができます。

メンテナーがこのコメントをすると、プルリクエストを開いた人（およびリポジトリを監視している他の誰もが）通知を受け取ります。これについては後でカスタマイズ方法を説明しますが、もしTonyがメール通知をオンにしていれば、次のようなメールを受け取ります。

誰でもプルリクエストに一般的なコメントを残すことができます。プルリクエストのディスカッションページでは、プロジェクトオーナーがコードの行にコメントし、その後にディスカッションセクションに一般的なコメントを残す例を見ることができます。コードコメントも会話に取り込まれていることがわかります。

これで、貢献者は自分の変更が承認されるために何をすべきかを知ることができます。幸い、これは非常に簡単です。メールでは、シリーズを再作成してメーリングリストに再提出する必要があるかもしれませんが、GitHubでは、トピックブランチに再度コミットしてプッシュするだけで、プルリクエストが自動的に更新されます。プルリクエストの最終表示では、古いコードコメントが更新されたプルリクエストで折りたたまれていることも確認できます。これは、変更された行に対してコメントが付けられたためです。

既存のプルリクエストにコミットを追加しても通知はトリガーされないため、Tonyは修正をプッシュした後、要求された変更を行ったことをプロジェクトオーナーに通知するためにコメントを残すことにしました。

興味深い点として、このプルリクエストの「Files Changed」タブをクリックすると、「統合」差分、つまりこのトピックブランチがマージされた場合にメインブランチに導入される総計の差分が表示されます。git diffの用語で言えば、このプルリクエストが基づいているブランチに対して、基本的にgit diff master…​<branch>が自動的に表示されます。この種の差分の詳細については、何が導入されるかを確認するを参照してください。

もう一つ気づくこととして、GitHubはプルリクエストがクリーンにマージできるかどうかをチェックし、サーバー上でマージを実行するためのボタンを提供します。このボタンは、リポジトリへの書き込みアクセス権があり、かつ簡単なマージが可能な場合にのみ表示されます。これをクリックすると、GitHubは「ノンファストフォワード」マージを実行します。これは、マージがファストフォワード可能であったとしても、マージコミットが作成されることを意味します。

よろしければ、ブランチをプルしてローカルでマージすることもできます。このブランチをmasterブランチにマージしてGitHubにプッシュすると、プルリクエストは自動的に閉じられます。

これがほとんどのGitHubプロジェクトが使用する基本的なワークフローです。トピックブランチが作成され、それに対してプルリクエストが開かれ、議論が行われ、場合によってはブランチでさらに作業が行われ、最終的にリクエストは閉じられるかマージされます。

多くのプロジェクトは、ほとんどのメーリングリストベースのプロジェクトがパッチシリーズの貢献を考えるように、プルリクエストを順序通りにきれいに適用されるべき完璧なパッチのキューとは考えていないことを理解することが重要です。ほとんどのGitHubプロジェクトは、プルリクエストブランチを提案された変更を巡る反復的な会話と捉えており、マージによって適用される統合差分として最終的に集約されます。

これは重要な区別です。なぜなら、一般的に変更はコードが完璧だと考えられる前に提案されるからです。これはメーリングリストベースのパッチシリーズの貢献でははるかに稀です。これにより、メンテナーとの早期の会話が可能になり、適切な解決策にたどり着くことがコミュニティの取り組みとしてより強くなります。プルリクエストでコードが提案され、メンテナーまたはコミュニティが変更を提案した場合、パッチシリーズは通常再ロールされず、代わりに差分が新しいコミットとしてブランチにプッシュされ、以前の作業のコンテキストを維持したまま会話が進みます。

例えば、プルリクエストの最終表示をもう一度見直すと、貢献者がコミットをリベースして別のプルリクエストを送信しなかったことがわかります。代わりに、彼らは新しいコミットを追加し、既存のブランチにプッシュしました。この方法だと、将来このプルリクエストを遡って見たときに、なぜそのような決定がなされたのかというすべてのコンテキストを簡単に見つけることができます。サイト上の「Merge」ボタンを押すと、プルリクエストを参照するマージコミットが意図的に作成され、必要に応じて元の会話を簡単に遡って調査できるようになります。

あなたのプルリクエストが古くなったり、クリーンにマージできなくなったりした場合、メンテナーが簡単にマージできるように修正したいと考えるでしょう。GitHubはこれをテストし、マージが簡単かどうかをすべてのプルリクエストの下部でお知らせします。

クリーンにマージされないプルリクエストのような表示を見た場合、ブランチを修正して緑色になるようにし、メンテナーが余分な作業をする必要がないようにしたいと考えるでしょう。

これを行うには、主に2つの選択肢があります。ターゲットブランチ（通常はフォークしたリポジトリのmasterブランチ）の上に自分のブランチをリベースするか、ターゲットブランチを自分のブランチにマージするかです。

GitHub上のほとんどの開発者は後者を選択します。これは、前のセクションで説明したのと同じ理由によるものです。重要なのは履歴と最終的なマージなので、リベースはわずかにクリーンな履歴が得られる以外には大したメリットがなく、その代わりにはるかに難しく、エラーが発生しやすくなります。

ターゲットブランチをマージしてプルリクエストをマージ可能にしたい場合は、元のリポジトリを新しいリモートとして追加し、そこからフェッチし、そのリポジトリのメインブランチをトピックブランチにマージし、問題を修正し、最後にプルリクエストを開いたのと同じブランチにプッシュし直します。

例えば、以前使用していた「tonychacon」の例で、元の作者がプルリクエストで競合を引き起こす変更を行ったとしましょう。その手順を見ていきましょう。

これを行うと、プルリクエストは自動的に更新され、クリーンにマージできるかどうかが再チェックされます。

Gitの素晴らしい点の1つは、これを継続的に実行できることです。非常に長期にわたるプロジェクトがある場合でも、ターゲットブランチから繰り返し簡単にマージでき、前回マージして以来発生した競合のみを処理すればよいため、プロセスを非常に管理しやすくなります。

もしどうしてもブランチをリベースして整理したいのであれば、もちろんそうすることはできますが、すでにプルリクエストが開かれているブランチに強制プッシュすることは強く推奨されません。もし他の人々がそのブランチをプルしてさらに作業を進めていた場合、リベースの危険性で概説されているすべての問題に遭遇することになります。代わりに、リベースされたブランチをGitHubの新しいブランチにプッシュし、古いプルリクエストを参照する新しいプルリクエストを開き、元のものを閉じます。

次の質問は「古いプルリクエストを参照するにはどうすればいいですか？」かもしれません。GitHubのほとんどどこにでも書き込みができる場所で、他のものを参照する方法はたくさんあります。

まず、別のプルリクエストやイシューを相互参照する方法から始めましょう。すべてのプルリクエストとイシューには番号が割り当てられており、プロジェクト内で一意です。たとえば、プルリクエスト #3 とイシュー #3 を同時に持つことはできません。他のプルリクエストやイシューから参照したい場合は、コメントや説明の中に単に#<num>と記述するだけで済みます。イシューやプルリクエストが別の場所にある場合は、より具体的に指定することもできます。現在のリポジトリのフォーク内のイシューやプルリクエストを参照する場合はusername#<num>、別のリポジトリのものを参照する場合はusername/repo#<num>と記述します。

例を見てみましょう。前の例でブランチをリベースし、新しいプルリクエストを作成したとします。そして今、新しいプルリクエストから古いプルリクエストを参照したいとします。また、リポジトリのフォーク内のイシューと、まったく別のプロジェクトのイシューも参照したいとします。説明はプルリクエスト内の相互参照のように記入できます。

このプルリクエストを送信すると、それらすべてがプルリクエストにレンダリングされた相互参照のようにレンダリングされているのを見ることができます。

そこに入力した完全なGitHub URLが、必要な情報のみに短縮されたことに注目してください。

さて、もしTonyが元のプルリクエストを閉じた場合、新しいプルリクエストでそれを言及することで、GitHubがプルリクエストのタイムラインに自動的にトラックバックイベントを作成したことがわかります。これは、このプルリクエストを訪れてそれが閉じられていることを確認した人が誰でも、それを置き換えたプルリクエストに簡単にリンクを戻せることを意味します。リンクはクローズされたプルリクエストのタイムラインから新しいプルリクエストへのリンクのようになります。

イシュー番号に加えて、SHA-1で特定のコミットを参照することもできます。40文字の完全なSHA-1を指定する必要がありますが、GitHubがコメント内でそれを見つけると、コミットに直接リンクします。同様に、イシューで行ったのと同じ方法で、フォークや他のリポジトリのコミットを参照できます。

最初の本当に便利なGitHub固有のMarkdown機能、特にプルリクエストでの使用に適しているのは、タスクリストです。タスクリストは、完了したいことのチェックボックスのリストです。これらをイシューやプルリクエストに入れることは、通常、その項目を完了とみなす前に完了したいことを示します。

このようにタスクリストを作成できます

これをプルリクエストやイシューの説明に含めると、Markdownコメントにレンダリングされたタスクリストのように表示されます。

これはプルリクエストで、プルリクエストがマージ可能になるまでにブランチで完了したいことを示すためによく使用されます。本当に素晴らしい点は、チェックボックスをクリックするだけでコメントを更新できることです。タスクをチェックオフするためにMarkdownを直接編集する必要はありません。

さらに、GitHubはイシューとプルリクエスト内のタスクリストを探し、それらを一覧表示するページにメタデータとして表示します。たとえば、タスクを含むプルリクエストがあり、すべてのプルリクエストの概要ページを見ると、それがどこまで完了しているかを確認できます。これは、人々がプルリクエストをサブタスクに分割するのに役立ち、他の人々がブランチの進捗を追跡するのに役立ちます。この例はプルリクエストリストのタスクリストの概要で確認できます。

これらは、プルリクエストを早期に開き、機能の実装の進捗を追跡するために使用する場合に非常に役立ちます。

コメントにコードスニペットを追加することもできます。これは、ブランチにコミットとして実際に実装する前に、試してみる可能性のある何かを提示したい場合に特に便利です。また、これは動作しないコードの例や、このプルリクエストが実装できるものを示すためにもよく使われます。

コードスニペットを追加するには、それをバッククォートで「囲む」必要があります。

「java」のように言語名を追加すると、GitHubはそのスニペットを構文ハイライトしようとします。上記の例の場合、レンダリングされたフェンス付きコードの例のようにレンダリングされます。

長いコメントの一部に返信する際は、行の前に>文字を付けて、他のコメントから選択的に引用できます。実際、これは非常に一般的で便利なため、キーボードショートカットがあります。コメント内の直接返信したいテキストをハイライトし、rキーを押すと、そのテキストがコメントボックスに引用されます。

引用は次のようになります

レンダリングされると、コメントはレンダリングされた引用例のようになります。

最後に、コメントで絵文字を使用することもできます。これは、多くのGitHubのイシューやプルリクエストで見られるコメントで実際にかなり広く使われています。GitHubには絵文字ヘルパーもあります。コメントを入力中に:文字で始めると、オートコンプリート機能があなたが探しているものを見つけるのに役立ちます。

絵文字はコメントのどこでも:<name>:の形式を取ります。例えば、次のように書くことができます

レンダリングされると、絵文字を多用したコメントのようになります。

これが非常に役立つというわけではありませんが、感情を伝えるのが難しい媒体に、楽しさや感情の要素を追加することは確かです。

これは厳密にはGitHubフレーバーのMarkdownではありませんが、非常に便利です。コメントにMarkdownの画像リンクを追加する（URLを見つけて埋め込むのが難しい場合がある）だけでなく、GitHubでは画像をテキストエリアにドラッグ＆ドロップして埋め込むことができます。

画像をドラッグ＆ドロップしてアップロードし、自動的に埋め込むを見ると、テキストエリアの上に「Parsed as Markdown」という小さなヒントが表示されているのがわかります。それをクリックすると、GitHubでMarkdownを使ってできることの完全なチートシートが表示されます。