GitHub の Saved replies でレビューコメントにラベルをつける
こういう感じで GitHub のレビューコメントにラベルを付けています。
効果として、
- レビューコメントのスタンスがレビュイーに明確に伝わる
- 対応するべきか、そのままでもいいかレビュイーが判断しやすい
などを期待しています。 ただし、それぞれの意味や対応方針をレビュアーとレビュイーの間で合意しておく必要はあります。
簡易的には、テキストのみのラベルでも十分伝わると思います。以前はそういう運用をしていました。 しかし、画像のほうが視覚的に判別しやすいと思い、最近は画像でラベルを表現するようにしています。
しかし画像を貼り付けるのは面倒
一方で、画像やその URL をレビューコメントに毎回貼り付けるのは少々手間です。 そこで GitHub の Saved replies に定型文として登録して、入力の手間を省きます。
GitHub Saved replies
https://github.com/settings/replies からアカウントの Saved replies を設定します。
画像ラベルの作り方
画像は https://shields.io/ で生成する SVG を使います
SVG を生成する URL のパターンは https://shields.io/ に書いてある通りで、 https://img.shields.io/badge/<LABEL>-<MESSAGE>-<COLOR>
で指定します。
たとえば、 Suggest の場合は以下の URL を使っています。色は好みのものを使いましょう。
https://img.shields.io/badge/review-suggest-success.svg
あとはこれを Markdown で見れる形にして Saved replies に放り込むだけです。
![suggest](https://img.shields.io/badge/review-suggest-success.svg)
実際に Saved replies を利用して画像ラベルを挿入する様子
おまけ
以下は、僕がレビューコメントで用いているラベルとその意味です。
Must fix
- 絶対直してくれというレベル
- Request changes で投げることが多い
- 明らかに仕様を満たしていないとか、セキュリティ的にまずい実装など
- あるいはコードにコミットするべきでない物が混入したときなど
- 何らかのシークレットや顧客の情報など、コードが漏洩した際に悪影響があるもの
Should
- 言葉通り、こうすべき、というニュアンスで使う
- 機能仕様は満たしてるかもしれないけど、パフォーマンス上の懸念があるとき
- フレームワークの扱い方
Suggest
- こう書いたほうがいいよ
- 後述の In my opinion より、客観的に推奨するもの
- たとえば、 Laravel にはこういう便利なヘルパーがあってな、とか
In my opinion
- こういうふうに書いたほうがいいと思う、という意見
- あくまでレビュアーの意見の一つでしかなく、取り入れるかはレビュイーに任せる、という扱い
nits
- typo やコーディングスタイルなどの軽微なミス
- これ直したあとでマージしてよ、くらいのノリで Approve と一緒に投げることもある
Ask
- レビュイーへの質問
Boyaki
- ぼやき、そのまんんま
- コードスメルがありそうなところ
- このレビューを通して修正するには問題が根深かったり、大きすぎるとき
- いずれリファクタリングしたいねというような結論にして、 issue を切る事が多い