これは何?
- この記事は GENDA Advent Calendar 2023 の 19日目の記事です
- 直近所属したいくつかの組織で提案している GitHub の Pull Request (以下PR) の進め方のガイドラインです
目的
- PR をスムーズに完了させ、プロダクトリリースサイクルを早く回す
- 非同期コミュニケーションの中で最低限のコミュニケーションで PR を完了させる
通知の設定
- PR をスムーズに完了させ、プロダクトリリースサイクルを早くする
- 非同期コミュニケーションの中で最低限のコミュニケーションで PR を完了させる
- 定時通知やリアルタイム通知を設定できる
マージ方針
- 1人以上のレビューを通すこと
- PR済みの機能をリリース用ブランチに取り込む際はこの限りではない
タイトル
- 'チケット名'␣'一行で説明'
- ex) XX-123 問い合わせURL変更
description
- テンプレートに従って必要項目を記入
- UIの変更は画像や動画を貼ると、テキストよりも情報量が多く伝わりやすい
- 画像は
を使うと表示されるサイズが大きすぎて見にくくなる-
<img alt="alt" src="image_url" width="393px" />のように、 @1x サイズのwidthを指定すると見やすくなる - また before/after はテーブル表記にすると横に並んで比較しやすくなる
- 基本的な書き方とフォーマットの構文 - GitHub Docs
-
コミット
- コミットメッセージにチケット番号を記載する
- 将来不具合調査などに有効
- コミット内容がわかるようにお願いします
- "fix", "レビュー対応" だけでは何をしたか不明
- PR時にコミットを一つにまとめなくてよい
Reviewers
- 1人以上を設定
- 相互レビュー推奨。自分がレビュアーにアサインされていなくても手が空いたときなどは積極的にレビューする
Asignees
- 現在誰がボールを持っているかを把握するために活用している
- レビュー待ちであればレビュアーを Asignees に設定する
- レビューコメントの対応待ちであればPR作成者を Asignees に設定する
Milestone
- リリースすべきバージョンが決まっていれば設定する
レビュイー (レビューされる側)
- レビュアーの負荷を下げよう
- この手間が最終的にPRがマージされるまでの時間が短くなる
- 大きな変更の PR は小さく分割する
- 大きすぎる PR は本質的な指摘が難しくなる
- 小さく分割できない場合説明する時間を設けてもよい
- 検証方法を明記する
- 準備の手間が大きい場合は、再現性のあるアカウント情報を記載する
- 指摘に対応する際は、同一PR内に指摘された箇所以外にも同じ問題がないか確認しておく
- プライベート端末のスクリーンショットや動画を載せるときは個人情報が写り込まないようにしたり、マスクする
- iOSシミュレータの録画機能よりもmacのスクリーンレコーディング (⌘+Shift+5) がおすすめ
- マウスポインターが見えるので操作対象がわかる
- ボタン操作などを伴う動画の場合、iPhone実機やシミュレータの録画機能では操作対象がわからない。画面遷移したときなど、何をして画面遷移が発生したか理解しにくい
- シミュレータのウィンドウのヘッダも含めることで、端末の種類・OSバージョンもわかる
- GitHubに動画ファイル動画を貼付するとURL文字列しか表示されないため、video タグで囲うと見やすい
<video alt="動画が表示されない環境に向けてざっくり説明" src="動画のURL" />
レビュアー (レビューする側)
- 一行の修正なら suggestion
- コメントの typo とか
- 複数箇所の修正はコミットも複数になってしまう (本当か?)
- 指摘を修正し終わったら ♺マークをクリックする
- Reviewer に再度通知が飛ぶ
- Reviewer に再度通知が飛ぶ
- Hide whitespace
- スペースやタブの変更を無視する設定
- if文が追加された時、if中の処理がすべてインデントされただけで、処理に本質的な変更がない場合などに有効
- 実装意図を教えてもらうようなコメントをした場合、コード上にコメントを追記してもらう
- 読み手がわからなかったコードは、PR参加者以外がコードを読んだときにも同じ疑問を持つため
- 直してほしいのか、ただの感想なのか、レビュイーがアクションに移せるような情報を与える
Discussion