プルリクエストのコメントにはラベルバッジをつける
コメントの温度感が伝わらない問題を、must / imo / ask / nit pick といったラベルで解決し、さらにバッジ化とコマンド化まで進める話です。
- 公開日
この記事は別サイトにも掲載しています。 https://qiita.com/iganin/items/aee297eade84849cc9cd
はじめに
Git を使用したプルリクエストのコメントに対する対応の際に、そのコメントに対して温度感がわからず戸惑ってしまうといった体験はありませんでしょうか。必須で対応が必要なのか、ただの意見なのか… 結局判断がつかず、直接聞く、Slack で確認するなど場合によっては不要なコミュニケーションが発生してしまい、コストに繋がってしまいます。 本記事ではそのような事態を避ける方法として以下を紹介します。
- プルリクエストのコメントにラベルをつける
- ラベルを視認しやすくするためにバッジにする
- バッジ付与をコマンド化し効率的に付与できるようにする
1. プルリクエストにラベルをつける
実践されている方も多いかもしれませんが、プルリクエストのコメントにそのコメントの意味合いをラベルとして付与すると「はじめに」に記述したような事態を避けることができます。具体的には以下のようなものをコメントの先頭に付与します。
| ラベル | 意味 |
|---|---|
| must | 対応必須 この対応がされていないとマージを認められない |
| imo | in my opinion 自分ならこう実装するけど、どう？ |
| ask | 実装意図の確認 |
| nit pick | 細かい指摘（コードを整える、不要な改行など） |
| suggestion | 提案、このようにしたらどうか |
例えば下記のようになります。
[imo]
enum の switch 文では default は使用せずに全て網羅して記述した方が良いと思いますがいかがでしょうか。
将来的に case が追加され、その case が網羅されていない際にコンパイラが検知してくれるためです。
default を使用した場合は、該当ケースが網羅されていなくてもそのケースは default にながれてしまい、
バグが生まれる原因になりかねません。2. ラベルを視認しやすくするためにバッジにする
1 の方法をおこなうことで改善できるかと思いますが、より視認性をあげることができそうです。 たとえば、バッジ画像をつかう方法があります。 例えば、1 の must の場合は下記のようなものを使用します。
行なっていることは、Markdown の画像付与です。
上記のようにした場合下記の HTML のように変換され、画像が表示されます。
<img src="https://img.shields.io/badge/review-must-red.svg" title="must" />ここで具体的な画像の URL が問題になりますが、shields.io 経由で簡単にバッジ画像を取得することができます。バッジ作成は下記の構文で行います。
https://img.shields.io/badge/<SUBJECT>-<STATUS>-<COLOR>.svgSUBJECT が画像の左側の文言、STATUS が画像の右側の文言、COLOR が画像の右側の色になります。 上記 must のバッジでは下記のようになります。
- SUBJECT = review
- STATUS = must
- COLOR = red
色は red, blue など shields.io で定義されているものの他に ffffff のような hex 形式も使用可能です。 shields.io の HP では様々なサンプルも掲載されています。 詳細は、公式ページおよび本記事の参考資料をご覧ください。
1 でご紹介したラベルとバッジ画像の対応は例えば下記のようになります。
| ラベル | 画像 | 構文 |
|---|---|---|
| must | |
 |
| imo |  |
 |
| ask |  |
 |
| nit pick |  |
 |
| suggestion |  |
 |
3. バッジ付与をコマンド化し効率的に付与できるようにする
上記画像付与ですが、毎回書くのはもちろん手間になりますし、どこかにテキストをまとめておき、コピー & ペーストするのもあまり良いやり方とは言えません。Text Blaze を使用することでこの問題を解決することができます。 Text Blaze は特定の文字列をコードスニペットに自動変換するよう登録することができるツールです。 ※ 執筆時点ではまだ β バージョンのようです。 ※ 無料アカウントではグループ作成数や登録スニペット数に上限があるなどいくつかの制限があります。
使用方法
簡単な使用方法を記載します。 詳細は Text Blaze の公式 HP をご参照ください。
1: Text Blaze HP にアクセスし、Add To Chrome を押下し Chrome Extension をインストールします
2: インストールした Text Blaze の Chrome Extension を押下し、アカウントの作成もしくは Google Account との連携を行います
3: ホーム画面左上の項目からフォルダを押下しグループを作成し、プラスボタンを押下しグループ内にスニペットを作成します。
4: 作成したスニペットに必要な情報を入力します。
- Snippet Description - 画面左側に表示される文言です
- Shortcut - type to trigger - この文字列を入力することで登録したスニペットに変換されます
- 画面下部 - 変換後のスニペットを登録します
以上、1 〜 4 の作業によってスニペットへの変換を登録できます。これ以後は Google Chrome を使用中に登録した ShortCut 文字列を入力すれば登録したスニペットに変換されます。例えば、画像の例の場合は /must と入力することで  に変換されるようになります。
まとめ
本記事では、Git でのプルリクエストの際にラベルを付与することで温度感やニュアンスを伝える方法、バッジを付与する方法と付与方法を簡単にする Text Blaze というツールをご紹介しました。 本記事の方法によって、プルリクエスト時のコミュニケーションコストを減らすことに寄与できたら嬉しいです。 良い開発ライフを！
参考資料
Git のプルリクエストのコメントについて
- レビューコメントにラベルをつけるだけで開発効率があがって幸せになれそうな話 - Qiita
- レビューコメントにラベルをつけるアイデアに関して記載されています。
- GitHub「完璧なプルリクの書き方を教えるぜ」 - Qiita
- プルリクエスト時の注意点がまとまっており、大変参考になります。
- プルリク時のコメント略語 - Qiita
- MUST, IMO などの意味について記載してあります。
バッジの作成について
- shields.io
- shields.io の HP です。さまざまサンプルと使用方法が記載されています。
- Markdown 記法 チートシート - Qiita
- Markdown の書き方です。画像表示の方法だけではなく、code の表示、List の表示など多岐に渡る説明があります。
- shields.io 経由でだいたいなんでも自由にバッジ表示する - Qiita
- shields.io を使用したバッジの作成方法が記載されています。
Text Blaze、コードスニペットについて
- プルリクのコメントにタグ付けして意図を伝える - Qiita
- Text Blaze とバッジに関する説明が記載されています。
- Text Blaze
- Text Blaze の公式 HP です。