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つだけ）と、プロジェクトの所有者によってこのブランチがマージされた場合に加えられるすべての変更の統一diffも表示されます。

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

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

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

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

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

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

既存のプルリクエストへのコミットの追加は通知をトリガーしないため、Tonyは修正をプッシュした後、プロジェクトの所有者に変更を加えたことを知らせるコメントを残すことにしました。

注目すべき興味深い点は、このプルリクエストの「Files Changed」タブをクリックすると、「統一」diffが表示されることです。つまり、このトピックブランチがマージされた場合にメインブランチに導入される合計の集計差です。git diff用語では、基本的には、このプルリクエストのベースとなっているブランチに対してgit diff master…​<branch>を自動的に表示します。このタイプのdiffの詳細については、導入されたものの特定を参照してください。

もう1つ気づくことは、GitHubがプルリクエストがクリーンにマージされるかどうかを確認し、サーバーでマージするためのボタンを提供することです。このボタンは、リポジトリへの書き込みアクセス権があり、簡単なマージが可能である場合にのみ表示されます。それをクリックすると、GitHubは「非早送り」マージを実行します。つまり、マージが早送り可能な場合でも、マージコミットを作成します。

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

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

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

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

たとえば、戻ってプルリクエストの最終をもう一度見ると、コントリビューターがコミットをリベースして別のプルリクエストを送信していないことに気付くでしょう。代わりに、彼らは新しいコミットを追加し、既存のブランチにプッシュしました。このようにして、将来このプルリクエストに戻って調べると、決定が下された理由のすべてのコンテキストを簡単に見つけることができます。サイトで「マージ」ボタンを押すと、プルリクエストを参照するマージコミットが意図的に作成されるため、必要に応じて元の会話を簡単に調べて調べることができます。

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

プルリクエストがクリーンにマージされないのようなものが表示された場合は、ブランチが緑色に変わり、メンテナが追加の作業を行う必要がないように修正する必要があります。

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

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

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

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

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

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

ブランチをクリーンアップするためにリベースしたい場合は、そうしても構いませんが、プルリクエストがすでに開かれているブランチに force push しないことを強くお勧めします。他の人がそれをプルダウンしてさらに作業を進めている場合、リベースの危険性で概説されているすべての問題に直面することになります。代わりに、リベースしたブランチをGitHubの新しいブランチにプッシュし、古いプルリクエストを参照する新しいプルリクエストを開き、元のものを閉じます。

次の疑問は、「古いプルリクエストをどのように参照すればよいのか？」ということかもしれません。実は、GitHubで記述できるほぼすべての場所で、他のものを参照する方法はたくさんあります。

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

例を見てみましょう。前の例でブランチをリベースし、それに対する新しいプルリクエストを作成し、新しいプルリクエストから古いプルリクエストを参照したいとします。また、リポジトリのフォークにあるIssueと、完全に別のプロジェクトにあるIssueも参照したいとします。プルリクエストの相互参照のように、説明を記入することができます。

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

完全なGitHub URLは、必要な情報だけに短縮されていることに注意してください。

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

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

特にプルリクエストで使用する場合に非常に役立つ最初のGitHub固有のMarkdown機能は、タスクリストです。タスクリストは、実行したいことのチェックボックスのリストです。通常、Issueまたはプルリクエストに入れることは、アイテムが完了したと見なす前に実行したいことを示すものです。

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

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

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

さらに、GitHubはIssueとプルリクエストでタスクリストを探し、それらをリストするページにメタデータとして表示します。例えば、タスクを含むプルリクエストがあり、すべてのプルリクエストの概要ページを見ると、どれだけ完了しているかを確認できます。これにより、人々はプルリクエストをサブタスクに分割でき、他の人々はブランチの進行状況を追跡できます。プルリクエストリストでのタスクリストの概要でこれの例を見ることができます。

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

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

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

上記のように 'java' で言語名を追加すると、GitHubはスニペットの構文を強調表示しようとします。上記の例の場合、レンダリングされたフェンスコードの例のようにレンダリングされます。

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

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

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

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

絵文字は、コメント内の任意の場所で :<name>: の形式をとります。例えば、次のように記述できます

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

これが非常に役立つとは限りませんが、感情を伝えるのが難しいメディアに、楽しさと感情の要素を追加します。

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

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