GitHub のプルリクエストを美しく書くための小技集

この記事は YUMEMI Advent Calendar 2022 4 日目の記事です。

ゆめみでは、 GitHub + プルリクエスト駆動での開発が基本となっており、日々大量のプルリクエストが飛び交っています。
当然コードレビューの工数も比例して掛かってくるため、プルリクエストの書き方を工夫してレビュワーの負荷軽減に努めています。

そこで、今回はプルリクエストをより美しく書くために、個人的によく利用している小技についてまとめてみました。

それぞれの表示・動作については以下での確認となっています。

• 2022 年 12 月 4 日時点
• macOS + Google Chrome

メディア表示系

画像を小さく表示

ドラッグ & ドロップすることで、画像をプルリクエストに貼り付けることができますが、そのままだと Markdown 記法となってしまうため、原寸大で表示されてしまいます。

アップロード後の Markdown 形式

![ファイル名](https://user-images.githubusercontent.com/アップロード先URL.png)

画像を特定サイズで表示したい場合は、アップロード先の画像 URL を src 属性として利用して img タグに変換してしまいます。

img タグに変換してのサイズ指定

<img width="640" alt="ファイル名" src="https://user-images.githubusercontent.com/アップロード先URL.png">
<img width="320" alt="ファイル名" src="https://user-images.githubusercontent.com/アップロード先URL.png">

対象	スクリーンショット
Markdown 記法
width="640"
width="320"

動画をテーブル組み

以前は対応していなかったのですが、2021年頃から動画に関してもドラッグ & ドロップでアップロード + プレイヤーの表示に GitHub 側が対応してくれています.¹

実際に試してみると、 Markdown 記法ではなく単純なアップロード先 URL という形で展開されます。

アップロード後の表示

https://user-images.githubusercontent.com/アップロード先URL.mp4

単純な URL 形式のため、修正前後の表示を行うためにテーブル組みを行った場合では動画プレイヤーがインライン展開されずに困ったことになります。

これを回避するために、アップロード先の動画 URL を src 属性として利用して video タグに変換。
これで、動画のテーブル組みが実現できます。

動画のテーブル組み

|Before|After|
|:-:|:-:|
|<video src="https://user-images.githubusercontent.com/アップロード先URLその1.mp4">|<video src="https://user-images.githubusercontent.com/アップロード先URLその2.mp4">|

動画プレイヤーの上部に表示されるタイトル部分については、アップロード時の動画ファイル名が利用されるため、こだわる場合はアップロード前にファイル名を変更してください。

引用系

コードのインライン参照

レビュワーに関連するコード部分を示したいといった場合に、以下のようにインライン展開した状態でコードを示すことができます。

対応手順としては、以下の通りです。

1. 対象のコードを GitHub 上で確認
2. 行を選択して、 Copy permalink で該当行へのリンクをクリップボード上に取得
   • ブランチ名やタグ名に依存するものではなく、コミットハッシュに依存した形式の URL となります
3. クリップボードからペースト
4. 複数行指定する場合はリンクのアンカー部分を L${開始行数}-L${終了行数} に変更

複数行の指定例

https://github.com/hugehoge/Snappable/blob/806de8123c87fdd818f1b8998a56417a1a510007/Example/CarouselExample/CarouselExample/Components/CarouselView.swift#L12-L25

プルリクエスト や Issue のインライン展開

GitHub ではプルリクエストや Issue の番号に沿った #39 のような表記を自動的にリンクに展開してくれます。

これだけでも十分なのですが、 Markdown のリスト形式で表現してあげると、該当項目のタイトル等をインライン展開してくれます。

リスト表記によるインライン展開

- #39
- [ ] #39
    - チェックボックスとも合わせられる

修飾系

カラーコード表示

カラーコード表示

`#ABCDEF`

のように、 HEX 値をインラインコード扱いすることで、対応するカラーが横に追加表示されます。

diff をハイライト表示

Markdown のコードブロックを利用する際に言語を指定して、シンタックスハイライトを効かせることができるのは有名ですが、この言語として diff を指定することができます。

このため、git diff の結果をプルリクエストの説明欄やコメントに記載したいとなった場合に diff なコードブロックを利用することで、いい感じに表示してくれます。

diff をハイライト表示

​```diff
diff --git a/fizzbuzz.swift b/fizzbuzz.swift
index 64dff72..a982e50 100644
--- a/fizzbuzz.swift
+++ b/fizzbuzz.swift
@@ -1,12 +1,12 @@
 import Foundation
 
 let result: [String]  = (1...100).map { i in
-  if i % 3 == 0 {
+  if i % 15 == 0 {
+    return "FizzBuzz"
+  } else if i % 3 == 0 {
     return "Fizz"
   } else if i % 5 == 0 {
     return "Buzz"
-  } else if i % 15 == 0 {
-    return "FizzBuzz"
   } else {
     return String(i)
   }

​```

冗長な記述を折りたたみ

どうしても必要だけど冗長になってしまう記述ブロック等があると、プルリクエストの説明欄がどうしても縦に長くなってしまいます。

全体ではコンパクトにまとめてレビュー時の可読性を担保しつつ、冗長な記述を追加したいとなった場合には <details> タグと <summary> タグを利用してアコーディオン展開可能にするといったことが可能です。

特にスクリーンショット画像の数が多い場合や上述の diff を載せるとなった場合に効果的です。

折りたたみ表示

<details>
<summary>修正前後の動作</summary>

|Before|After|
|:-:|:-:|
|<video src="https://user-images.githubusercontent.com/アップロード先URLその1.mp4">|<video src="https://user-images.githubusercontent.com/アップロード先URLその2.mp4">|

</details>

<details>
<summary>diff 全文</summary>

​```diff
diff --git a/fizzbuzz.swift b/fizzbuzz.swift
index 64dff72..a982e50 100644
--- a/fizzbuzz.swift
+++ b/fizzbuzz.swift
@@ -1,12 +1,12 @@
 import Foundation
 
 let result: [String]  = (1...100).map { i in
-  if i % 3 == 0 {
+  if i % 15 == 0 {
+    return "FizzBuzz"
+  } else if i % 3 == 0 {
     return "Fizz"
   } else if i % 5 == 0 {
     return "Buzz"
-  } else if i % 15 == 0 {
-    return "FizzBuzz"
   } else {
     return String(i)
   }

​```

</details>

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市、郊外のぎらぎらひかる草の波。

状態	スクリーンショット
格納
展開

1. https://github.blog/2021-05-13-video-uploads-available-github/ ↩