共同開発をするにあたってこんなことありませんか？
「これなんのプルリクなん？」
「そもそも何してるの？」
「あれ？どの機能を修正してるんだっけ？」
「バグの原因は？解決策は？」
「どのコミットで何をしているの？」
このようにプルリクエスト(PR)の書き方が開発チーム内で共有出来ていないと各々が好きな方法でPRを作成するのでレビュアーは管理する事が難しい．
本記事ではプルリクエストの書き方の例とそれをチーム内で共有することの大切さを記載する．
他のチートシート
git/gh コマンド(PRの概要については以下の記事を参考にすること(gitの基本))
lazygit
ステータスコード
Docker コマンド
TypeScript
Go
SQL
ファイル操作コマンドチートシート
Vim
VSCode Github Copilot拡張機能
OpenAI Assistants API
他のシリーズ記事
TypeScriptで学ぶプログラミングの世界
プログラミング言語を根本的に理解するシリーズです．
情報処理技術者試験合格への道 [IP・SG・FE・AP]
情報処理技術者試験の単語集です．
IAM AWS User クラウドサービスをフル活用しよう！
AWSのサービスを例にしてバックエンドとインフラ開発の手法を説明するシリーズです．
そもそも
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
注釈・警告などのアラート(Qiitaでは)
補足説明
:::note info
補足説明
:::
警告
:::note warn
警告
:::
禁止
:::note alert
禁止
:::
注釈・警告などのアラート(Githubでは)
> [!NOTE]
> 書き留め
> [!TIP]
> 追加説明
> [!IMPORTANT]
> 重要事項
> [!WARNING]
> 警告事項
> [!CAUTION]
> 注意事項
チケットリンクやコミットハッシュ(Githubでは)
issueなどのチケットリンクを貼りたい際はその該当の数字のまえに#をつけて記述する．
#123
コミットのリンクを貼りたい場合はコミットハッシュを入力する．
12ab45c
コードの任意の部分を指定
ソースコードの任意の部分を表示できる．qiitaではそのリンクとなるが，GithubのPRでは以下の画像のようにコードが表示される．
https://github.com/[アカウント名]/[リポジトリ名]/blob/[コミットハッシュ]/[ディレクトリ名]/[ファイル名]#L[始まり行番号]-L[終わり行番号]
https://github.com/[アカウント名]/[リポジトリ名]/blob/[コミットハッシュ]/[ディレクトリ名]/[ファイル名]まではファイルをGithub上で開く時のリンクであるので任意のコミットでの任意のファイルのリンクをコピーしてからそのリンクの後に#L[始まり行番号]-L[終わり行番号]をつければいい．例えば1行目から12行目なら#L1-L12となる
このようにマークダウンを使って見やすいPRや技術ブログを作成しよう！ここからはPRにフォーカスして美しいPRを作成する方法について紹介する．
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の状態に応じてタスク管理することが可能．以下の記事を参考にすること．
これ以外のマークダウン記法は以下の記事を参考にすること
Markdown記法 チートシート