めも

メモ.

プルリクエストの際の説明の書き方について

この記事は何

何かを開発→プルリクエスト→レビューされてマージ、というのが普段の開発の流れだと思います。 最近、いろいろな人(自分がよく知らない人も含めて)にレビューされる機会が増えたので、どんなことを書けば良いかを確認。

メモ

自分が他の人のコードを確認するとして

  • プルリクエストに対応するissue・案件へのリンクがある or はっきりと対応していると分かる
  • なぜその変更を行ったかが分かる
  • 変更内容を確かめる手順が分かる
  • どのようにして挙動が正しいとチェックしたかが分かる

と嬉しいので、これらの内容がはっきりと伝わるようにする。 フォーマットが指定されている場合はそれに従う(普段見慣れているものが一番わかりやすいはずなので)。

の『Remember that anyone in the company could be reading this Pull Request,(会社の中の誰しもがあなたのプルリクエストを読んでいる可能性があることを心に留めておいてください、)』ことを忘れないようにしたいです。

また、レビューしてもらうということはフィードバックがあるはずなので

  • どのようなフィードバックが欲しいか
  • 誰がこのコードや機能の詳細に詳しいか・誰が関係しているか

も明記すべき時は記述する。

にてプルリクエストのテンプレートが作成できるので、基本的にはチームや開発メンバーで決めたテンプレートに従う。まとめると

# issue/JIRA等の対応するタスクへのリンク
# なぜこの変更を行ったか
# 変更内容の説明
# 確認手順
# レビュー・フィードバック等に関する補足

みたいな感じでしょうか。

そして、プルリクエストのコメント以外でもこのプルリクエストで一時的に対応した箇所にTODOコメントをつけたり、全体で共有すべき内容はドキュメントとして残すことも忘れないようにしたい。

参考文献