この記事は freee Engineers Advent Calendarの6日目です。
こんにちは。freee株式会社でアプリエンジニアをしている @kompiroです。主に会計freeeの開発に携わっています。
僕には「よりよい機能を、より早くユーザーに届けたい」という信念があります。今日はよりよい機能を、より早くユーザーに届けるためのGit/GitHubを活用する10の方法と題してGitやGitHubの便利な使い方や日々のTipsをお届けします。1
PRのレビュー完了までの時間を最速にするための工夫
freeeではGitHub上でレビューをしながら開発を進めています。レビューをするのもされるのも、うまく進めないと結構時間がかかります。もちろんコードをより良くする作業に時間を割いているのであれば時間がかかるのも致し方ないです。しかし、進め方による問題でも数日〜数週間デプロイが延期されれば、それだけユーザーに価値が届くまで時間が遅くなります。
そうならないよう、レビューする時、自分なりにツールを活用したり、ルールを決めたりして運用しています。
レビューする時は、下記の点に注意しています。
- 1. PRにアサインされたら少なくとも次の営業日までにコメントをする
- 2. アサインされているPRがアップデートされたら、その日のうちにレスを返す
- 3. コードの書き方で宗教論争になりそうな点は、コメントとして一言書くだけにする
- 4. コードを読んでみてわからないことには「わからない」と反応する
- 5. 動作に問題がある時は、アニメーションGIFを撮影しコメントに貼って状況を共有する
PRを作成する時は、下記の点に注意しています。
- 6. PRはできるだけ小さな単位で作成する
- 7. PRのレビューを依頼する前に、コードコメントにするほどではないが変更点の説明が必要な箇所には予めコメントをしておく
- 8. レビューアがPRにコメントをつけるなど、アップデートされたら速やかに反応する
- 9. PRの概要にはスクリーンショットをつけたり、操作したアニメーションGIFを貼るのと、確認手順を明記する
- 10. PRテストの結果を見てからマージボタンを押すことを忘れない
それぞれについて見ていきましょう。
レビューする編
1. PRにアサインされたら少なくとも次の営業日までにコメントする
PRを作成した後は、みんなできるだけ早くリリースしたいもの。僕は特にそういうたちなので、アサインされたら少なくとも次の営業日までにレビューし、コメントを返すようにしています。
Slackなどの通知は、業務に集中するため本当に必要なもの以外切っていますが、GitHubの通知は別です。PRにアサインされたらできるだけ早く反応できるようにしています。僕はSafariユーザーなのでNotifier for GitHub任せですが、Macを利用されているのであれば gitify もオススメです。
PRのチェックアウトでは、できるだけ早くPRのオーナーと同じ環境にするため、いくつかのツールと設定を組み合わせています。まず最初に紹介したいのは hub です。hubはGitHubを使うためにgitをより便利にしたCUIラッパーです。hubをインストールすると、PRをチェックアウトしたい時はcheckoutの引数にURLを指定するだけで済むようになります。
git checkout https://github.com/brigade/overcommit/pull/376
hubのインストールは簡単です。Homebrewをインストール済みであれば
$ brew install hub
$ alias git=hub
の2行で済みます。
次はovercommitです。overcommitはGitのフック管理を行うツールで、手元ではチェックアウト時に bundle update と npm update を行うようにしています。依存するライブラリが更新された際、これらの操作を忘れないようにしています。詳しい使い方は拙Qiitaの記事を見ていただけると幸いです。
3つ目に紹介したいのはdirenvです。direnvはディレクトリごとに環境変数を設定できるツールで、プロジェクトごとに環境変数を設定しておくことでレビュー時の切り替え忘れを防止しています。こちらも詳しい使い方は拙Qiitaの記事をご参照ください。
最後はRailsの設定です。freeeではRailsのプロジェクトが多いのですが、レビューをする際、あらかじめマイグレーションが必要なのに忘れることが多々ありました。次の設定をしておくとマイグレーション忘れがある場合はページ読み込み時にエラーになるので、マイグレーション忘れを防げます。
config.active_record.migration_error = :page_load
これだけやっておくと、レビューを始める時の環境に差異がほとんどなくなるので、快適にレビューを始められます。
GitHubでレビューをつける時はコメントをつける度に通知が飛ばないよう、Add a single commentではなくStart a reviewボタンを押すようにしています。
2. アサインされているPRがアップデートされたら、その日のうちにレスを返す
アサインされているPRがアップデートされたら、できるだけ早く反応するようにしています。もし、PRのオーナーが何度かpushしているようであれば修正が終わったら連絡してもらうようにコメントを残し、自分の作業に戻ります。
アサインされているPRがどれだったか忘れてしまった場合は、Pull RequestのAssignedのページを開くとすぐに見つかります。GitHubのUIから開きたい場合は次の手順で開けます。
3. コードの書き方で宗教論争になりそうな点は、コメントとして一言書くだけにする
以前はコードフォーマットに関する指摘もレビュー時にやることになっていました。しかし、RubocopやESLintを導入してくれた同僚のおかげでフォーマットの指摘をすることは少なくなってきました。
反面、コードを読んでいると同僚の癖の部分が気になるようになってきました。具体的にパフォーマンスや問題があるコードでなければコメントを一言書くだけにしています。プログラミングにはどうしても宗派みたいなものがあります。コード上の細かな差に目を向けて足を止めるより、別のことに時間をつかうようにしています。
4. コードを読んでみてわからないことには「わからない」と反応する
レビュー中、わからないことには「わからない」と反応するのは案外大事です。というのも、コードを書いた人がうまく説明できないコードには、問題が潜むことも多いからです。PRのレビューでコメントをやりとりしていくうちに、PRのオーナーが書きたい事が明確になることも少なくありません。
わからないことに「わからない」と反応するのは、なにが「わからない」のかを伝えないとならないため、案外簡単ではないこともあります。ただ、なにも反応しないよりは良い結果が得られるでしょう。
5. 動作に問題がある時は、アニメーションGIFを撮影しコメントに貼って状況を共有する
PRのレビューでは必ず動作確認も行うようにしています。動作確認をしようとして、手順がわからなかったり、どういう風に動くべきなのか、期待結果がわからない時も先程のように「わかりません」とコメントするようにしています。実際に動かしてみて動作が怪しい時は再現手順と、実際に問題を再現させたスクリーンキャプチャやアニメーションGIFを貼るようにしています。
スクリーンキャプチャの撮影にはSkitch、アニメーションGIFの撮影にはGIPHY Captureを利用しています。どちらもWebのサービスと連携が必要に見えますが、ローカルにファイルを保存でき、使い勝手がよいです。
PR作成編
6. PRはできるだけ小さな単位で作成する
PRをレビューする側からすると、たくさんの変更があるPRはレビューも骨が折れるもの。コミットと同様、小さくPRを作成し、メインラインにマージする方が総じて短い時間でレビューが済みます。レビューをする人にとって、コードの変更が多量にあるPRは、見落としが増えがちになるでしょう。
コミットにしろPRにしろ、小さくまとめるコツは「1つの事で1つのコトしかしない」ことです。言い換えると、コミットはコードとして意味ある変更の単位で、PRはプロダクトとして意味ある単位の変更の単位で作成するように心がけています。これだけだと大きさを伝えづらいと思うので、コミットメッセージとPRのサマリーを幾つか書いてみます。
コミットメッセージの例
-
モデルの追加 -
Rubocopによる自動修正 -
Specの追加
PRのサマリーの例
- ○○をUIから作成できるようにした
- ○○を一覧に表示できるようにした
- 新機能を開発するための初期ファイルを追加した
大体1つのPRあたり5-10コミット、総変更行数が多くとも300行くらいに収まると、レビューが数時間で終わり、デプロイまで長くて2日で済みます。
freeeで開発しているアプリケーションには新機能の有効/無効を管理する機能が用意されています。既存機能に影響を与えないように開発を進めているので、開発中のPRをマージしても問題ありません。
以前は大きな機能はその機能用のフィーチャーブランチを用意し、そこにトピックブランチをマージしていくことがありましたが、フィーチャーブランチに開発ブランチをマージする手間などを考えると小さくマージをしていったほうが効率がよいです。
7. PRのレビューを依頼する前に、コードの変更内容に説明が必要な箇所には、予めレビューコメントをつけておく
レビューアに速やかにレビューを進めてもらうには、コードを読むときの引っ掛かりを減らすことが大事です。特に削除したコードを説明したい時は、PRを作成後、説明が必要な箇所にレビューコメントを予め書いてからレビューを依頼するようにしています。
意図や考えを伝達するために、できることはやっておいたほうが、より早くより良い機能を開発できるでしょう。
8. レビューアがPRにコメントをつけるなど、アップデートされたら速やかに反応する
レビューアがPRのレビューを終えるよりも前に修正を始め、指摘事項の修正も早く終えられれば、修正後の確認も別のタスクを始める前に依頼できるかもしれません。レビューアにしてみると、レビュー中のPRに修正が入るとコメントしづらいことがあります。それも含めPRコメントでやり取りすると良いでしょう。
もし、レビューアがたくさんコメントを残しているようであれば、コメントが書かれるのを待ってから対応した方がよい場合もあります。そういう場合は待ちましょう。
9. PRの概要にはスクリーンショットをつけたり、操作したアニメーションGIFを貼るのと、確認手順やこのPRでやっていないことを明記する
UIに変更点があるなら、画面が崩れていることに気づけるよう、BeforeとAfterの画像を比較できるようにPRに添付しましょう。もし操作が複雑ならどうなるのかがわかるアニメーションGIFを用意し、PRに貼っておきましょう。
それとは別に、レビューアが何を確認すればよいかわかるよう、PRの確認手順や確認してほしいことや、逆にこのPRで実現できてないことを説明に書くようにしましょう。PRのレビューアがどこまで確認すればよいのかわからないPRは、なかなかレビューが難しいので、放置されてしまいます。何を見たらよいのか、わかるようにしておきましょう。
10. CIの結果が通ってからマージボタンを押せるようにする
PRのレビューにて、時々CIのチェックが終わる前にLGTMが出ることもあるでしょう。GitHubの設定で、CIの結果がpassになる前にマージボタンを押すことを禁止できます。詳しくはGitHubのヘルプを見てみてください。
おわりに
以上、PRレビューを円滑に進めるための10の方法でした。日々自分が気にしていることもあれば、開発の困りごとを減らすために導入したツールだったり、マイルールを紹介してみたのですがいかがだったでしょうか？自分としては「よりよい機能をより早く届ける」ことはfreeeの価値基準で言う「マジ価値」です。freeeではより多くのユーザーに「マジ価値」を届けるエンジニアを募集しています。
明日はかがやきのアイドルモバイルマスター @bl-lia の登場です。おたのしみに。
-
UMLやDDDなどオブ厨話はまた別の機会に。 ↩