共同開発をするにあたってこんなことありませんか？
「これなんのプルリクなん？」
「そもそも何してるの？」
「あれ？どの機能を修正してるんだっけ？」
「バグの原因は？解決策は？」
「どのコミットで何をしているの？」
このようにプルリクエスト(PR)の書き方が開発チーム内で共有出来ていないと各々が好きな方法でPRを作成するのでレビュアーは管理する事が難しい．
本記事ではプルリクエストの書き方の例とそれをチーム内で共有することの大切さを記載する．
PRの概要については以下の記事を参考にすること(gitの基本)
https://qiita.com/tarakokko3233/items/ad7e1a1a14d3e2f10da3
そもそも
PRはソースコードと一緒に提出するおまけではない．また，単にソースコードの説明をして，マージするための判断材料でもない．
PRの目的は
1.変更箇所をレビューし，マージしても大丈夫かどうか判断する
2.後で開発した機能が不具合を起こした時にどのPRでの作業が原因か特定する
3.他の開発者とのすり合わせ
大まかにこのような目的だろう．
マークダウン記法とは
マークダウン記法で書くとPRが見やすくなる．マークダウン記法の書き方は以下の記事を参考にしてほしい．
Markdown記法 チートシート
ここからはよく使うマークダウン記法をピックアップする
インライン表示
A
`A`
コードブロック
print("markdown")
```example.py
print("markdown")
```
数式(Tex記法)
\frac{1}{2}\left( \sum_{k=1}^n a_k b_k \right)^{\!\!2}
```math
\frac{1}{2}\left( \sum_{k=1}^n a_k b_k \right)^{\!\!2}
```
見出し
# 見出し
## 見出し
### 見出し
イタリック体
italic
*italic*
太字
bold
**bold**
打ち消し線
打ち消し
~~打ち消し~~
引用
引用
引用
>引用
>>引用
水平線
***
リンク
[Qiita](http://qiita.com)
箇条書きリスト
- 1
- 1-1
- 1-2
- 2
- 2-1
- 2-2
- 2-2-1
- 2-2-2
- 1
- 1-1
- 1-2
- 2
- 2-1
- 2-2
- 2-2-1
- 2-2-2
PR作成前チェックポイント
あるブランチにおいてPRを作成する際にどんなことを意識したらいいだろうか．
何も考えずにただPRを作成するのはやめよう
以下に意識すべき点をまとめる．
-
コンフリクトの解消
当たり前です -
エラー解消
エラーはもちろんだが，警告もできるならば解消したい -
動作確認
マージ先ブランチで動かないなんてことのないように
PRのドラフト機能
PRをOpenで作成するのではなくDraftで作成することができる．
Openとは以下のような状態のこと
これだと，
誤ってマージされることがある
ので以下のようなdraft状態でPRを作成しても良い
この状態だと
- マージできない
- 作成中のコードを共有できる
- DraftでもCIツールは動く
完成はしていないが途中で他のチームメンバーに見てほしいという際に便利である．
Draftの作成方法
Create pull requestの横のプルダウンから選択して作成できる
またはOpenで作成した際にreviewerの欄の下にConvert to draftがあるのでここでも変更可能．
Draftの解除方法
Ready for reviewを選択すれば解除できる．この画像を見ると，Draft状態ではMerge Pull requestは押せないようになっていることがわかる．
実際にPRを作成しよう
PR作成したら確認すべき点と．コメントに書くべき内容をまとめる．
PR作成後の確認点
-
変更差分の確認
- 余計なコミットがないか？
- 不要なコメント文の確認
- 不要なprint文，console log文，Debug.Logなどデバッグコードの確認
- タイポや関数名の不備はないか？
-
CIツールは動いていますか？
CIツール自体がエラーを吐いていないか？また，CIツールがソースコードの問題点を示唆していないか？ -
PRの送り先はあっているか？
稀に，PRの送り先が間違えてしまうことがあるので気をつけよう．
ここのbaseがマージ先，compareがマージ元
PRを作成した際にFile changedの欄がある．ここを押すと，このPR全体での変更差分が確認できる．
この不要なコード1つでコンフリクトを起こすこともあるので注意しよう．
-
まとめられるコミットはないか？
git rebase -iや，git reset --softを用いて複数のコミットをまとめられる．pjによって変わると思うが，細かな変更のコミット数が多すぎると見にくいPRとなる．
コミットをまとめる方法は以下の記事から
-
PRでどんなコメントをするといいのか
-
概要
PRの概要 -
新機能の対応内容/バグの原因と対処法
新機能の作成をしたなら対応内容を簡単に箇条書きにする．バグなら生じた原因と対処法を記載 -
変更によって生じた結果のキャプチャ
結果の画像や出力などあると良い -
再現/実行時のコマンドや注意点
レビュアーや他のチームメンバーが実行する際の実行コマンドと注意点を記載する -
(任意)問題点や課題
このPRで作成できなかったことがあれば記載しておく．他のタスクに分割する，などあればかく． -
(Draftならば)改善したいがわからないのでレビューを求める
わからなかったことやパフォーマンスを上げる手法を尋ねるにはどうするかを記載するとよい -
その他
デモ動画，画像や参考文献を書くと良い．
-
概要
マージ前に確認すること
最後にPRをマージする際に気をつけることをまとめる．まあ，今まで確認したことの集大成である．
- コンフリクト，エラーはないですか？
- 動作確認はしましたか？
- 変更差分の確認(コミットの集約)はしましたか？
- PRの送り先はあっていますか?
- PRのコメントは丁寧に書きましたか？
全部確認してからマージしよう．
PRの状態に応じてタスク管理することが可能．以下の記事を参考にすること．
おまけ(Qiitaで使うマークダウン記法)
ここからはPRで使うマークダウン記法ではなく，Qiitaで使うマークダウン記法について説明する
補足説明(Qiitaでは)
補足説明
:::note info
補足説明
:::
警告説明(Qiitaでは)
警告
:::note warn
警告
:::
禁止説明(Qiitaでは)
禁止
:::note alert
禁止
:::
これ以外のマークダウン記法は以下の記事を参考にすること
Markdown記法 チートシート