プルリクエスト・マークダウン記法チートシート[共同開発の8割はプルリクエストの書き方で決まる！]

共同開発をするにあたってこんなことありませんか？
**「これなんのプルリクなん？」**
**「そもそも何してるの？」**
**「あれ？どの機能を修正してるんだっけ？」**
**「バグの原因は？解決策は？」**
**「どのコミットで何をしているの？」**

このようにプルリクエスト(PR)の書き方が開発チーム内で共有出来ていないと各々が好きな方法でPRを作成するのでレビュアーは管理する事が難しい．
本記事ではプルリクエストの書き方の例とそれをチーム内で共有することの大切さを記載する．


# 他のチートシート
git/gh コマンド(PRの概要については以下の記事を参考にすること(gitの基本))

https://qiita.com/JavaLangRuntimeException/items/6b46551f56e0def76eba

lazygit

https://qiita.com/JavaLangRuntimeException/items/42087d09728d5739d73d

ステータスコード

https://qiita.com/JavaLangRuntimeException/items/ab1bc7b976ed2dfad91c

Docker コマンド

https://qiita.com/JavaLangRuntimeException/items/21f7c7bf3d143f821697

TypeScript

https://qiita.com/JavaLangRuntimeException/items/5894391c08e0d8e28389

Go・Gorm

https://qiita.com/JavaLangRuntimeException/items/d388717fc1436bc3ec9d

testing/gomock

https://qiita.com/JavaLangRuntimeException/items/bf521190f6f4d79e59fb

C#/.NET/Unity

https://qiita.com/JavaLangRuntimeException/items/7849b32bc223d4aa0247

Ruby・Ruby on Rails

https://qiita.com/JavaLangRuntimeException/items/42d935cf92c212f1c7ec

SQL

https://qiita.com/JavaLangRuntimeException/items/f038fbaccdd92fb0308a

ファイル操作コマンドチートシート

https://qiita.com/JavaLangRuntimeException/items/16f244606a73f7d106e4

Vim

https://qiita.com/JavaLangRuntimeException/items/0c68ab96ea198e0a7294

VSCode Github Copilot拡張機能

https://qiita.com/JavaLangRuntimeException/items/be13dc3a346cf6e5ee44

OpenAI Assistants API

https://qiita.com/JavaLangRuntimeException/items/1a1abc01e8d7d05dce93

Github API

https://qiita.com/JavaLangRuntimeException/items/4f3551c31679233219ac

変数・関数(メソッド)・クラス命名規則

https://qiita.com/JavaLangRuntimeException/items/b93865c448f69bcfca4a

# 他のシリーズ記事
**TypeScriptで学ぶプログラミングの世界**
プログラミング言語を根本的に理解するシリーズです．

https://qiita.com/JavaLangRuntimeException/items/cadf49bb419076819963

**情報処理技術者試験合格への道[IP・SG・FE・AP]**
情報処理技術者試験に出題されるコンピュータサイエンス用語の紹介や単語集

https://qiita.com/JavaLangRuntimeException/items/991be402099542ccb936

**IAM AWS User クラウドサービスをフル活用しよう！**
AWSのサービスを例にしてバックエンドとインフラ開発の手法を説明するシリーズです．

https://qiita.com/JavaLangRuntimeException/items/371a334f5a6e07035db5

**AWS UserのGCP浮気日記**
GCPの様子をAWSと比較して考えてみるシリーズ

https://qiita.com/JavaLangRuntimeException/items/527d99e774165a763180

**Project Gopher: Unlocking Go’s Secrets**
Go言語や標準ライブラリの深掘り調査レポートです．

https://qiita.com/JavaLangRuntimeException/items/dc45b412d3fbd2ccb9e8

**Gopher’s Journey: Exploring TCP Protocol**
Goを用いてTCPプロトコルを探求 & 作成するシリーズです．

https://qiita.com/JavaLangRuntimeException/items/38091220106d86651d2b

# そもそも
PRはソースコードと一緒に提出するおまけではない．また，単にソースコードの説明をして，マージするための判断材料でもない．
PRの目的は

**1.変更箇所をレビューし，マージしても大丈夫かどうか判断する**

**2.後で開発した機能が不具合を起こした時にどのPRでの作業が原因か特定する**
**3.他の開発者とのすり合わせ**

大まかにこのような目的だろう．

# マークダウン記法とは
マークダウン記法で書くとPRが見やすくなる．マークダウン記法の書き方は以下の記事を参考にしてほしい．
[Markdown記法 チートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)

ここからはよく使うマークダウン記法をピックアップする

## インライン表示
`A`
~~~md:Aをインライン表示したいとき
`A`
~~~
## コードブロック
```example.py
print("markdown")
```

~~~md:example.pyをコードブロックで書きたい時
```example.py
print("markdown")
```
~~~


## 数式(Tex記法)

```math
\frac{1}{2}\left( \sum_{k=1}^n a_k b_k \right)^{\!\!2} 
```
~~~md:数式を書きたい時
```math
\frac{1}{2}\left( \sum_{k=1}^n a_k b_k \right)^{\!\!2} 
```
~~~


## 見出し
~~~md:見出しの書き方(h1タグ)
# 見出し
~~~
~~~md:見出しの書き方(h2タグ)
## 見出し
~~~
~~~md:見出しの書き方(h3タグ)
### 見出し
~~~

## イタリック体
*italic*
~~~md:イタリック体の書き方
*italic*
~~~
## 太字
**bold**
~~~md:太字の書き方
**bold**
~~~

## 打ち消し線
~~打ち消し~~
~~~md:打ち消し線の書き方
~~打ち消し~~
~~~

## 引用
> 引用
>> 引用
~~~md:引用の書き方
> 引用
>> 引用
~~~

## 水平線
***
~~~md:水平線の書き方
***
~~~

## リンク
[Qiita](http://qiita.com)

~~~md:水平線の書き方
[Qiita](http://qiita.com)
~~~

## 箇条書きリスト
- 1
  - 1-1
  - 1-2
- 2
  - 2-1
  - 2-2
    - 2-2-1
    - 2-2-2

~~~md:箇条書きリストの書き方
- 1
  - 1-1
  - 1-2
- 2
  - 2-1
  - 2-2
    - 2-2-1
    - 2-2-2
~~~


## 注釈・警告などのアラート(Qiitaでは)
:::note info
補足説明
:::
~~~md:補足説明の書き方
:::note info
補足説明
:::
~~~
:::note warn
警告
:::
~~~md:警告説明の書き方
:::note warn
警告
:::
~~~

:::note alert
禁止
:::
~~~md:禁止説明の書き方
:::note alert
禁止
:::
~~~

## 注釈・警告などのアラート(Githubでは)

![スクリーンショット 2024-07-16 14.49.57.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/1010b282-fd86-6a44-f5a0-a5399eb83835.png)


```
> [!NOTE]
> 書き留め

> [!TIP]
> 追加説明

> [!IMPORTANT]
> 重要事項

> [!WARNING]
> 警告事項

> [!CAUTION]
> 注意事項

```

## チケットリンクやコミットハッシュ(Githubでは)
issueなどのチケットリンクを貼りたい際はその該当の数字のまえに#をつけて記述する．
```md:チケットリンク(issueやPRのリンクを貼る)
#123
```
コミットのリンクを貼りたい場合はコミットハッシュを入力する．
```md:コミットハッシュ
12ab45c
```
## コードの任意の部分を指定
ソースコードの任意の部分を表示できる．qiitaではそのリンクとなるが，GithubのPRでは以下の画像のようにコードが表示される．
![スクリーンショット 2024-07-16 15.08.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/4515561f-f7f6-5fc8-2311-5456eb9104e5.png)


```md:コードの行を指定して表示
https://github.com/[アカウント名]/[リポジトリ名]/blob/[コミットハッシュ]/[ディレクトリ名]/[ファイル名]#L[始まり行番号]-L[終わり行番号]
```

:::note info 
`https://github.com/[アカウント名]/[リポジトリ名]/blob/[コミットハッシュ]/[ディレクトリ名]/[ファイル名]`まではファイルをGithub上で開く時のリンクであるので任意のコミットでの任意のファイルのリンクをコピーしてからそのリンクの後に`#L[始まり行番号]-L[終わり行番号]`をつければいい．例えば1行目から12行目なら`#L1-L12`となる
:::

このようにマークダウンを使って見やすいPRや技術ブログを作成しよう！ここからはPRにフォーカスして美しいPRを作成する方法について紹介する．

# PR作成前チェックポイント
あるブランチにおいてPRを作成する際にどんなことを意識したらいいだろうか．

**何も考えずにただPRを作成するのはやめよう**

以下に意識すべき点をまとめる．
- **コンフリクトの解消**
  当たり前です
- **エラー解消**
  エラーはもちろんだが，**警告**もできるならば解消したい
- **動作確認**
  マージ先ブランチで動かないなんてことのないように

# PRのドラフト機能
PRを`Open`で作成するのではなく`Draft`で作成することができる．
`Open`とは以下のような状態のこと
![スクリーンショット 2024-06-13 11.02.58.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/8882c4d9-b78b-21f0-0e34-8b3c14582e09.png)


これだと，
**誤ってマージされることがある**
ので以下のような`draft`状態でPRを作成しても良い

![スクリーンショット 2024-06-13 11.04.32.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/585fba29-2b59-3afb-83f2-afabeadff667.png)

この状態だと
- **マージできない**
- **作成中のコードを共有できる**
- **DraftでもCIツールは動く**

完成はしていないが途中で他のチームメンバーに見てほしいという際に便利である．


## Draftの作成方法
`Create pull request`の横のプルダウンから選択して作成できる
![スクリーンショット 2024-06-13 11.10.22.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/06b98f2b-1ac7-84e8-2d68-f31ded20b171.png)

または`Open`で作成した際に`reviewer`の欄の下に`Convert to draft`があるのでここでも変更可能．
![スクリーンショット 2024-06-13 11.11.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/7c6de80b-a937-ed08-1693-fd3dade9ffad.png)

## Draftの解除方法
`Ready for review`を選択すれば解除できる．この画像を見ると，`Draft`状態では`Merge Pull request`は押せないようになっていることがわかる．
![スクリーンショット 2024-06-13 11.13.00.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/b6ca3e73-e001-d0d4-a8e1-fdecdb8c01fa.png)

# 実際にPRを作成しよう
PR作成したら確認すべき点と．コメントに書くべき内容をまとめる．

## PR作成後の確認点 
- **変更差分の確認**
  - 余計なコミットがないか？
  - 不要なコメント文の確認
  - 不要なprint文，console log文，Debug.Logなどデバッグコードの確認
  - タイポや関数名の不備はないか？
   
- **CIツールは動いていますか？**
　CIツール自体がエラーを吐いていないか？また，CIツールがソースコードの問題点を示唆していないか？
- **PRの送り先はあっているか？**
　稀に，PRの送り先が間違えてしまうことがあるので気をつけよう．
 ![スクリーンショット 2024-06-13 12.33.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/fbd07070-4538-e9ff-f9b2-43bbb1d21dc8.png)
 ここの`base`がマージ先，`compare`がマージ元


PRを作成した際に`File changed`の欄がある．ここを押すと，このPR全体での変更差分が確認できる．
![スクリーンショット 2024-06-13 11.18.35.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3757442/2508253b-eedd-52a7-0889-9e337f59c6f4.png)

:::note warn
この不要なコード1つでコンフリクトを起こすこともあるので注意しよう．
:::

- **まとめられるコミットはないか？**
`git rebase -i`や，`git reset　--soft`を用いて複数のコミットをまとめられる．pjによって変わると思うが，細かな変更のコミット数が多すぎると見にくいPRとなる．

コミットをまとめる方法は以下の記事から

https://qiita.com/tarakokko3233/items/49a5f0c0b297baa0568e

- **PRでどんなコメントをするといいのか**
  - **概要**
  　PRの概要 
  - **新機能の対応内容/バグの原因と対処法**
  　新機能の作成をしたなら対応内容を簡単に箇条書きにする．バグなら生じた原因と対処法を記載
  - **変更によって生じた結果のキャプチャ** 
  　結果の画像や出力などあると良い
  - **再現/実行時のコマンドや注意点**
  　レビュアーや他のチームメンバーが実行する際の実行コマンドと注意点を記載する
  - **(任意)問題点や課題**
  　このPRで作成できなかったことがあれば記載しておく．他のタスクに分割する，などあればかく．
  - **(Draftならば)改善したいがわからないのでレビューを求める**
  　わからなかったことやパフォーマンスを上げる手法を尋ねるにはどうするかを記載するとよい
  - **その他**
  　デモ動画，画像や参考文献を書くと良い．

 # マージ前に確認すること
 最後にPRをマージする際に気をつけることをまとめる．まあ，今まで確認したことの集大成である．
 - **コンフリクト，エラーはないですか？**
 - **動作確認はしましたか？**
 - **変更差分の確認(コミットの集約)はしましたか？**
 - **PRの送り先はあっていますか?**
 - **PRのコメントは丁寧に書きましたか？**

 全部確認してからマージしよう．

 PRの状態に応じてタスク管理することが可能．以下の記事を参考にすること．
 
 https://qiita.com/tarakokko3233/items/9a1eca7c5c84357b06bf


これ以外のマークダウン記法は以下の記事を参考にすること
[Markdown記法 チートシート](https://qiita.com/Qiita/items/c686397e4a0f4f11683d)