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

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

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

分散Gitで提示されているワークフローでは、この会話は電子メールで行われるかもしれませんが、GitHubではオンラインで行われます。プロジェクトオーナーは統一差分をレビューし、任意の行をクリックしてコメントを残すことができます。

メンテナがこのコメントをすると、プルリクエストを開いた人（そして、実際にはリポジトリを監視している他の誰でも）に通知が届きます。これについては後でカスタマイズしますが、彼が電子メール通知をオンにしていた場合、トニーは次のような電子メールを受け取るでしょう。

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

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

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

興味深いことの1つは、このプルリクエストの「Files Changed」タブをクリックすると、「統一された」差分、つまり、このトピックブランチがマージされた場合、メインブランチに導入される合計の集計差分が表示されることです。git diffの観点から言えば、基本的にこのプルリクエストが基づいているブランチに対してgit diff master...が自動的に表示されます。このタイプの差分の詳細については、導入されるものの決定を参照してください。

もう1つ注目すべき点は、GitHubがプルリクエストがクリーンにマージされるかどうかをチェックし、サーバー上でマージを実行するためのボタンを提供することです。このボタンは、リポジトリへの書き込みアクセスがあり、簡単なマージが可能な場合にのみ表示されます。これをクリックすると、GitHubは「非fast-forward」マージを実行します。つまり、マージがfast-forwardであったとしても、マージコミットが作成されます。

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

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

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

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

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

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

プルリクエストがクリーンにマージされないのようなものを見た場合は、ブランチを修正して緑色になり、メンテナが余分な作業をする必要がないようにする必要があります。

これを行うには、主に2つのオプションがあります。ターゲットブランチ（通常はフォークしたリポジトリのmasterブランチ）の上にブランチをリベースするか、ターゲットブランチをブランチにマージするかのどちらかです。

GitHubのほとんどの開発者は、前のセクションで説明したのと同じ理由で、後者を選択します。重要なのは履歴と最終的なマージなので、リベースは少しきれいな履歴以外にはほとんど得られず、その見返りにはるかに困難でエラーが発生しやすいです。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

上記のように「java」で言語名を追加すると、GitHubはスニペットのシンタックスハイライトも試みます。上記の例の場合、最終的にはレンダリングされたフェンスで囲まれたコード例のようにレンダリングされます。

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

引用は次のようなものです

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

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

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

レンダリングされると、大量の絵文字コメントのようになります。

これは信じられないほど便利だというわけではありませんが、感情を伝えるのが難しい媒体に、楽しさと感情の要素を加えます。

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

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