5
5

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

お題は不問!Qiita Engineer Festa 2024で記事投稿!
Qiita Engineer Festa20242024年7月17日まで開催中!

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

Last updated at Posted at 2024-06-13

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

このようにプルリクエスト(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をインライン表示したいとき
`A`

コードブロック

example.py
print("markdown")
example.pyをコードブロックで書きたい時
```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} 
```

見出し

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

イタリック体

italic

イタリック体の書き方
*italic*

太字

bold

太字の書き方
**bold**

打ち消し線

打ち消し

打ち消し線の書き方
~~打ち消し~~

引用

引用

引用

引用の書き方
> 引用
>> 引用

水平線


水平線の書き方
***

リンク

Qiita

水平線の書き方
[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では)

スクリーンショット 2024-07-16 14.49.57.png

> [!NOTE]
> 書き留め

> [!TIP]
> 追加説明

> [!IMPORTANT]
> 重要事項

> [!WARNING]
> 警告事項

> [!CAUTION]
> 注意事項

チケットリンクやコミットハッシュ(Githubでは)

issueなどのチケットリンクを貼りたい際はその該当の数字のまえに#をつけて記述する.

チケットリンク(issueやPRのリンクを貼る)
#123

コミットのリンクを貼りたい場合はコミットハッシュを入力する.

コミットハッシュ
12ab45c

コードの任意の部分を指定

ソースコードの任意の部分を表示できる.qiitaではそのリンクとなるが,GithubのPRでは以下の画像のようにコードが表示される.
スクリーンショット 2024-07-16 15.08.37.png

コードの行を指定して表示
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とは以下のような状態のこと
スクリーンショット 2024-06-13 11.02.58.png

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

スクリーンショット 2024-06-13 11.04.32.png

この状態だと

  • マージできない
  • 作成中のコードを共有できる
  • DraftでもCIツールは動く

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

Draftの作成方法

Create pull requestの横のプルダウンから選択して作成できる
スクリーンショット 2024-06-13 11.10.22.png

またはOpenで作成した際にreviewerの欄の下にConvert to draftがあるのでここでも変更可能.
スクリーンショット 2024-06-13 11.11.30.png

Draftの解除方法

Ready for reviewを選択すれば解除できる.この画像を見ると,Draft状態ではMerge Pull requestは押せないようになっていることがわかる.
スクリーンショット 2024-06-13 11.13.00.png

実際にPRを作成しよう

PR作成したら確認すべき点と.コメントに書くべき内容をまとめる.

PR作成後の確認点

  • 変更差分の確認

    • 余計なコミットがないか?
    • 不要なコメント文の確認
    • 不要なprint文,console log文,Debug.Logなどデバッグコードの確認
    • タイポや関数名の不備はないか?
  • CIツールは動いていますか?
     CIツール自体がエラーを吐いていないか?また,CIツールがソースコードの問題点を示唆していないか?

  • PRの送り先はあっているか?
     稀に,PRの送り先が間違えてしまうことがあるので気をつけよう.
    スクリーンショット 2024-06-13 12.33.19.png
    ここのbaseがマージ先,compareがマージ元

PRを作成した際にFile changedの欄がある.ここを押すと,このPR全体での変更差分が確認できる.
スクリーンショット 2024-06-13 11.18.35.png

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

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

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

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

マージ前に確認すること

最後にPRをマージする際に気をつけることをまとめる.まあ,今まで確認したことの集大成である.

  • コンフリクト,エラーはないですか?
  • 動作確認はしましたか?
  • 変更差分の確認(コミットの集約)はしましたか?
  • PRの送り先はあっていますか?
  • PRのコメントは丁寧に書きましたか?

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

PRの状態に応じてタスク管理することが可能.以下の記事を参考にすること.

これ以外のマークダウン記法は以下の記事を参考にすること
Markdown記法 チートシート

5
5
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
5
5

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?