今日は「【もりけん塾】GitHubでコードレビューを受けるときのお作法まとめ」をご紹介します。
こんにちは。Webコーダーのはるです。
最近、朝の時間を使ってJavaScriptの学習をしています。
私の所属している「もりけん塾」では、もりけんさん(@terrace_tec) が作成してくださったJavaScript課題で日々JavaScriptのコードレビューをしていただく機会があります。
最初はあれこれ戸惑ったので、GitHubを使用してコードレビューを受けるときのお作法をまとめてみます。（2023.04 現在）
新しく塾生になる方々や、塾の様子を知りたい方のご参考になればいいなぁと思います。
【もりけん塾】GitHubでレビューを受けるときのお作法まとめ
ここでは具体的に以下のことをまとめています。
- GitHubリポジトリの準備
- ローカルリポジトリの準備
- 開発ファイルの作成
- commit message(コミットメッセージ)
- StackBulitzの準備
- PR (プルリクエスト)の出し方
- レビューの依頼の仕方
- コードレビューの見方
- merge(マージ)までの流れ
共有点として、2021年7月からもりけん塾でのコードレビューは英語必須となりました。
- 今後英語に触れる機会をもっと増やして質の良い開発者になる
- 環境を変更することで英語漬けにする
以上が主な理由です。（なんて素晴らしい環境….(；ω；))
[もりけん塾]
– 7月からgithub上でのレビュー時、コメントのやりとりは全て英語になります
– 英語に慣れて自分に新たな付加価値をつけてもらう
– これからの海外エンジニアが入ってくる将来の為
英語を「奨励」することも検討しましたが、やめました。環境を丸っと変えないと定着しない為です pic.twitter.com/Go5J9DO54o— フロントエンドエンジニア (@terrace_tech) June 29, 2021
GitHub上の表記や、PRでのやりとり、コミットメッセージなども全て英語でおこないます。
GitHubリポジトリの準備
まず、課題を始める前にGitHubリポジトリを作成します。
GitHubと、StackBlitzのアカウントを用意してください。
2023.03から決められたディレクトリ構造で課題を進めることになりました。
もりけんさんの作成してくださったStackBlitzのテンプレートがあるので、そちらを使用して環境を作ります。
このようなテンプレートが出てくるので、左上のForkボタンを押します。
Forkされると、同じ環境が自分のStackBlitz内に作成されます。
タイトルで、fork版であることを確認したら「Connect repository」で GitHubと連携していきます。
pop upが出るので、リポジトリ名（決まりはないです）を入れて作成します。
左側に作成されたリポジトリと、自動で作成されたmainブランチが表示されます。
初回コミットがpushされています。
この状態でGitHubのマイページ -> Repositoryを開いて、作成したリポジトリをクリック。
無事にテンプレートからリポジトリを作成することができました。
ローカルリポジトリの準備
ローカルの環境を作成します。
git clone
git cloneしていきます。緑のCodeボタン > CloneのURLをコピーします。
次にターミナルを開き、以下のコマンドを実行。
$ cd cloneしたい先のディレクトリのパス
$ git clone 先程コピーしたURLcloneが成功したら、エディタから作成したディレクトリを開きます。VSCodeの場合は、以下のコマンドで簡単に開くことができます。
$ code .ちなみにcodeコマンドは設定がないと使えないので、必要であればこちらをご覧ください。
(任意) PR(プルリクエスト)のテンプレートを作成
git cloneができたら、ここでPRのテンプレートを作成しておくと便利です。
テンプレートを作成しておくと、PRでコメント欄に書くことを保存しておくことできてとても便利です。
手順は以下の記事がとてもわかりやすいので参考リンクを貼ります。
GitHub上でファイル作成したい場合は、以下の公式記事をご覧ください。
テンプレートにする内容は以下の通りです。
– レビュワーのために実際の問題文をある程度日本語で書く
## [CodeSandBox](リンク)
## Concerns and areas to focus on
– 実装上、不安なところ、重点的に見てもらいたいところ
– 該当箇所のコミットリンクなど
”最新のコミットリンク”は必要なくなったため削除しました。
GitHubを理解している塾生が増えたためです。（最新コミットは、PR画面下に積まれていきます）
マークダウン記法になっています。こちらを、pull_request_template.mdファイルに記述して保存すればOKです。
ちなみに私はローカルのmainブランチ内で作成して→リモートのmainにpushしました。(上記の手順リンクの1つ目の方法)。
また、最近はなるべく小さな粒度でPRを出すことが推奨されており、
## 前回実装した仕様
## 未実装の仕様
を書いておくと、レビュワーさんにより親切だと思います。
開発ファイルの作成
いよいよ開発ファイルを作成します。
ローカルリポジトリで新しくブランチを切ってから、新規ファイルの作成を行います。
mainブランチから以下のコマンドで新しいブランチを作成＆そのブランチに移動ができます。
$ git checkout -b ブランチ名私は一応、今どこのブランチにいるのかを確認してから作業を進めています。確認コマンド↓
$ git branch
ブランチができたら、ここで初めてhtmlやjsファイルを作成して開発を進めます。
ちなみに塾のDiscordを遡りましたが、ブランチ名の厳密な指定はないようです。
私は、feature/lesson01 のようにしています。
通常の開発ではgit-flowというブランチ管理のモデルが使用されることが多いとのことなので、これに沿って練習してみるのが良いかもしれません（私はmainとfeatureだけでやってしまっていますが）
commit message(コミットメッセージ)
ブランチを切ってファイルを作成→開発をしたら、まずローカルでgitの履歴を作成していきます。
$ git add --all
$ git commit -m "コミットメッセージ"ここに入れるコミットメッセージは、塾で規定があります。もりけんさんのハンズオンから引用です。
feat：新機能
refactor: リファクタリング
style: コードスタイル変更
fix：バグ修正
perf：パフォーマンスを向上させるコード変更
///
test: テスト修正
build：ビルドシステムまたは外部の依存関係に影響を与える変更
ci：CI構成ファイルとスクリプトの変更
doc：ドキュメントのみが変更されますこれらのプレフィックスを先頭につけて、その後に内容を入れます。
/* 例）新しい機能の追加 */
feat: add li to ul※ちなみに、課題１のコミットメッセージに最初「feat: lesson01/add li to ul」と書いていましたが、’lesson01’は不要だとレビューをいただきました。
「人間と機械が読みやすく、意味のあるコミットメッセージにするための仕様」という塾に貼ってあったリンクを共有します。
commitでローカルの履歴ができたら、リモートにpushします。
ちなみに、pushする前には必ず差分を確認するようにします。意図しないものをpushすることを防ぐためです。
/* addする前に変更点とインデックスとの差分を見る */
$ git diff
/* addした後にインデックスと最新コミットとの差分を見る */
$ git diff --cached
/* コミットした箇所を表示 */
$ git diff HEAD^などのコマンドで確認することができます。(何度やらかしたことか…pushしてから気付く絶望w)
内容をよく確認後、リモートにpushします。
$ git push origin head
StackBlitzのリンクを取得
最初の環境構築で作成したStackBlitzのデモを、レビュワーさんに共有します。
レビュワーさんのレビュー負担を軽減するためです。
① StackBlitzで作成したプロジェクトにアクセスする。
② 画像の矢印ボタンをクリックして、連携リポジトリからpull(最新の状態にする)。
ブランチ選択のプルダウンをクリックする。
③ PRしたいブランチを選択する。
④ メインで見ていただきたい該当 jsファイルをクリックして開く。
⑤ 上部メニューから「Share」を選択。モーダル内のCopy URLを押す。 
このリンクを下記で作るPRに添付してください。
PR (プルリクエスト)の出し方
ここまでできたら、PR(プルリクエスト)を出してレビューの依頼をします。
レビューの心得は、塾でシェアされていたこちらの記事が参考になります。
まず、リモートの開発用ブランチにpushすると、GitHubにこのようなメッセージが出るので「Compare & pull request」ボタンを押します。(今回の課題でスクショ撮っていなくて、昔の関係ないリポジトリの写真で失礼いたします。。)
すると下図のようなページが開きます。
② 最後のコミットメッセージがデフォルトで表示されるので、適したものに変更する
→ 非エンジニアの方が見ても分かるように、詳しく英語で説明します。
③ PRのコメント欄です。先ほどの「pull_request_template.md」の設定をすると、上図のような文言がデフォルトで表示されます。それぞれの課題用に書き換えます。
③に書く”最新のコミットリンク”は必要なくなりました。
GitHubを理解している塾生が増えたためです。（最新コミットは、PR画面下に積まれていきます）
※コメント欄の課題NO.のリンクには、もりけん先生のハンズオンに書かれている下図のリンクをそれぞれ貼ります。レビュワーさんが課題内容を確認しやすくするためです。
該当する課題のリンクに加えて、課題の概要も簡単に記述することになりました。
レビュワーさんの負担を軽減するためです。
すべて記述した後「Create pull reauest」ボタンを押下するとPRが完了です。
私のPR画面を貼ります。(レビューが終わってmergeした後に撮ったので、Mergedになってしまってますね。)
もし、一つの課題の中でPRを小分けにする場合は、今回のPRで実装した仕様もわかるように書いておきます。
レビューの依頼
PRの作成ができたら、Discordでレビューの依頼をします。
依頼するときは、PR画面のURLを必ず記載してレビュワーさんの負担を軽減します。
レビュー依頼をするときは、Discordのレビュー部屋に既に立てられている「課題1」などの該当スレッド内に依頼の投稿をすることになりました。毎回スレッドを立てる必要はありません。
またいただいたレビューに対して修正をした場合は
- CodeSandboxも修正
- 修正のコミット番号をPR画面のコメントでシェア
- Discordで連絡するときは、PRのURLを再度お伝えする
コードレビューの見方
コードレビューは全て英語で行われます。
塾では、レビュワーさんがコメントをくれる際に下記のようなラベルをつけてくださることがあります。このラベルは、修正の緊急度のようなものです。
IMO : 自分なら直すけどどう? 緩やかな指摘(In my opinion)
IMHO : 丁寧なIMO (In my humble opinion)
nits : 細かい指摘(nitpick)
FYI: 参考にするべきサイト
typo: タイポ
など
下記サイトから引用させていただきました。
merge(マージ)までの流れ
- 開発後にローカルにコミット→リモートにpush
- PR(プルリクエスト)を作成
- Discordでレビュー依頼
- レビューをいただいたら確認や修正
- 修正後に再度レビュワーさんに確認をしていただく
- レビュワーさんからApproveをいただいたら、mainブランチにmergeする(2名にApproveをいただいたらmerge可)
PR画面の下に「Merge pull request」ボタンを押下するとmergeできます。
次の課題に進むときは、リモートのmainブランチの内容を、ローカルのmainブランチにpullして、そこから新たに開発用のブランチを切って進めます。
このように1問が終わったら次の1問に進むようにして、1問目の修正を次の問題にも活かせるようにします。
開発ブランチの削除
mainにマージした後の開発ブランチ(feature/lesson01…など)は不要なので、リモート・ローカルともに消しておくのが一般的です。
mainにブランチ移動してから
/* ローカル：merge済みブランチの確認 */
$ git branch --merged [branchname]
/* ローカル：merge済みのブランチを削除*/
$ git branch -d [branchname]
/* リモート：ブランチを削除 */
$ git push --delete origin branchnameきちんとmergeされているか確認してから削除します。
コマンドは、こちらを参考にしました。
あとがき
課題に取り掛かるのが出遅れてしまったのですが、今までもりけん先生と塾生のみなさんがもりけん塾のレビューの流れや慣習を試行錯誤しながら作ってくださいました。
今回は、そのレビューのお作法を知ることができて大変勉強になりました。ありがとうございます。
課題も少しずつ進めていきたいと思います。
今日は以上です。
【もりけん塾に所属しています】
Thanks：師匠「もりけんさん」(@terrace_tec)
もりけんさんのHPはこちら
