【もりけん塾】GitHubでコードレビューを受けるときのお作法まとめ

Git

今日は「【もりけん塾】GitHubでコードレビューを受けるときのお作法まとめ」をご紹介します。

こんにちは。Webコーダーのはるです。

最近、朝の時間を使ってJavaScriptの学習をしています。

私の所属している「もりけん塾」でJavaScriptのコードレビューをしていただく機会があり、塾生のみなさんが常日頃から行っているレビューの流れを知りました。

最初はあれこれ戸惑ったので、GitHubを使ったコードレビューを受けるときのお作法をまとめてみます。(2021.07 現在)

新しく塾生になる方々や、塾の様子を知りたい方(?)のご参考になればいいなぁと思います。

ちなみに、もりけん先生(@terrace_tec) が作成してくださったJavaScript課題で学習→レビューしていただいています。

【もりけん塾】GitHubでレビューを受けるときのお作法まとめ

ここでは具体的に以下のことをまとめています。

  • GitHubリポジトリの準備
  • ローカルリポジトリの準備
  • 開発ファイルの作成
  • commit message(コミットメッセージ)
  • CodeSandboxの準備
  • PR (プルリクエスト)の出し方
  • レビューの依頼の仕方
  • コードレビューの見方
  • merge(マージ)までの流れ

共有点として、2021年7月からもりけん塾でのコードレビューは英語必須となりました。

  1. 今後英語に触れる機会をもっと増やして質の良い開発者になる
  2. 環境を変更することで英語漬けにする

以上が主な理由です。(なんて素晴らしい環境....(;ω;))

GitHub上の表記や、PRでのやりとり、コミットメッセージなども全て英語でおこないます。

GitHubリポジトリの準備

まず、課題を始める前にGitHubリポジトリを作成します。

GitHub上でのリポジトリ作成はこちらにまとめてあるので、”準備:まずはGitHub上でリモートリポジトリを作成” の部分をご覧ください。リポジトリ名に指定はありません。

手順の「git cloneします」の前に、GitHub上でREADME.mdにリポジトリの説明(英語)を書いておくとスムーズです。

作成したリポジトリのTOPページにある、README.mdの鉛筆マークを押すと編集できます。

リポジトリの説明をどのように書くかの指定はなく、私はこのように書きました。(もっと良い書き方があったら教えてください...)

ちなみにREADME.mdファイルを編集するときはマークダウン記法を使用します。マークダウン記法は、こちらのチートシートをブックマークしています。

ローカルリポジトリの準備

README.mdが書けたら、git cloneしていきます。緑のCodeボタン > CloneのURLをコピーします。

次にターミナルを開き、以下のコマンドを実行。

$ cd cloneしたい先のディレクトリのパス

$ git clone 先程コピーしたURL

cloneが成功したら、エディタから作成したディレクトリを開きます。VSCodeの場合は、以下のコマンドで簡単に開くことができます。

$ code .

(任意) PR(プルリクエスト)のテンプレートを作成

git cloneができたら、ここでPRのテンプレートを作成しておくと便利です。塾生の@hinapocoooさんから教わりました。ありがとうございます!

テンプレートを作成しておくと、PRでコメント欄に書くことを保存しておくことできてとても便利です。

手順は以下の記事がとてもわかりやすいので参考リンクを貼ります。

GitHub上でファイル作成したい場合は、以下の公式記事をご覧ください。

テンプレートにする内容は、もりけん先生がPRに書いて欲しい内容をまとめてくださっているので引用します。(先生のハンズオン課題より)

# [課題No](リンク)
## [CodeSandBox](リンク) :最新のコミットリンク

## 実装上、不安なところ、重点的に見てもらいたいところ
- コミットリンク
- コミットリンク

マークダウン記法になっています。こちらを、pull_request_template.mdファイルに記述→保存すればOKです。

ちなみに私はローカルのmainブランチ内で作成して→リモートのmainにpushしました。(上記の手順リンクの1つ目の方法)

開発ファイルの作成

いよいよ開発ファイルを作成します。

ローカルリポジトリで新しくブランチを切ってから、新規ファイルの作成を行います。

以下のコマンドで、新しいブランチを作成&作成したブランチに移動ができます。

$ git checkout -b ブランチ名

私は一応、今どこのブランチにいるのかを確認してから作業を進めています。確認コマンド↓

$ git branch

ブランチができたら、ここで初めてhtmlやjsファイルを作成して開発を進めます。

ちなみに塾のDiscordを遡りましたが、ブランチ名の厳密な指定はないようです。しかし、通常の開発では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

※ちなみに、課題1のコミットメッセージに最初「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

CodeSandboxの準備

塾では、レビューしてくださる方の負担を軽減するために、CodeSandboxでデモを用意します。

GitHubのリポジトリと連携ができるので、1からコードをコピペする必要はなく簡単です。

①まず、ご自身のCodeSandboxにログインをします。

②次に、TOPページ右上の「Create Sandbox」という青色のボタンを押下します。

③ポップアップが出てくるので、Import Project > Import GitHubのテキストフィールド欄に、GitHubのリポジトリURLを入れます。

ここに入れるリポジトリのURLは、index.htmlが置いてあるディレクトリのURLを入れる必要があります。

例えば私のリポジトリだと、こちらのTOPのURLではなく

こちらの見て欲しい課題(lesson01)を開いてindex.htmlのある状態で、https:~のURLをコピーします。

こうしないと、CodeSandboxのデモがうまく動きません。塾のDiscordで@ruby443nさんがご説明してくださっていました。ありがとうございます!

③URLをコピペしたら「Import and Fork」の青いボタンを押下

④これでデモが完成したはずです。右上の「Share」ボタンから、CopySandboxLinkを選べば、シェアのURLが取得できます。後ほど、PRのコメントで使用します。

PR (プルリクエスト)の出し方

ここまでできたら、PR(プルリクエスト)を出してレビューの依頼をします。

レビューの心得は、塾でシェアされていたこちらの記事が参考になります。

 

まず、リモートの開発用ブランチにpushすると、GitHubにこのようなメッセージが出るので「Compare & pull request」ボタンを押します。(今回の課題でスクショ撮っていなくて、昔の関係ないリポジトリの写真で失礼いたします。。)

すると下図のようなページが開きます。

① どのブランチからどのブランチへマージしたいのか選択
② 最後のコミットメッセージがデフォルトで表示されるので、適したものに変更する
→ JS課題では、「Feature : lesson01」のように書いている塾生さんが多かったです。
③ PRのコメント欄です。先ほどの「pull_request_template.md」の設定をすると、上図のような文言がデフォルトで表示されます。それぞれの課題用に書き換えます。

※コメント欄の課題NO.のリンクには、もりけん先生のハンズオンに書かれている下図のリンクをそれぞれ貼ります。レビュワーさんが課題内容を確認しやすくするためです。

2021.9.23  追記
該当する課題のリンクに加えて、課題の概要も簡単に記述することになりました。
レビュワーさんの負担を軽減するためです。

すべて記述した後「Create pull reauest」ボタンを押下するとPRが完了です。

私のPR画面を貼ります。(レビューが終わってmergeした後に撮ったので、Mergedになってしまってますね。)

レビューの依頼

PRの作成ができたら、Discordでレビューの依頼をします。

依頼するときは、PR画面のURLを必ず記載してレビュワーさんの負担を軽減します。

2021.9.23 追記
Discordのレビュー部屋にレビュー依頼を出したあとに、自分でスレッドを立てることになりました。自分の投稿したメッセージの右上にある「その他→スレッドの作成」で作成ができます。

またいただいたレビューに対して修正をした場合は

  • CodeSandboxも修正
  • 修正のコミット番号をPR画面のコメントでシェア
  • Discordで連絡するときは、PRのURLを再度お伝えする

コードレビューの見方

コードレビューは全て英語で行われます。

塾では、レビュワーさんがコメントをくれる際に下記のようなラベルをつけてくださることがあります。このラベルは、修正の緊急度のようなものです。

MUST : 必ず直すべき
IMO : 自分なら直すけどどう? 緩やかな指摘(In my opinion)
IMHO : 丁寧なIMO (In my humble opinion)
nits : 細かい指摘(nitpick)
FYI: 参考にするべきサイト
typo: タイポ
など

下記サイトから引用させていただきました。

merge(マージ)までの流れ

  1. 開発後にローカルにコミット→リモートにpush
  2. PR(プルリクエスト)を作成
  3. Discordでレビュー依頼
  4. レビューをいただいたら確認や修正
  5. 修正後に再度レビュワーさんに確認をしていただく
  6. レビュワーさんからApproveをいただいたら、mainブランチにmergeする(もりけん先生にApproveをいただくor 塾生さん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はこちら

タイトルとURLをコピーしました