こんにちは。マニュアル作成・ナレッジ共有ツール「NotePM」ブログ編集局です。
プルリクエストのテンプレートと例文をご紹介します。
マニュアル作成・ナレッジ共有ツール「NotePM」を無料でお試し！
プルリクエストとは？
プルリクエスト（Pull Request）とはソフトウェア開発時における修正内容を記した文書になります。修正内容（ソースコード）とプルリクエストを合わせて登録することで、システム管理者（修正内容をマージする権限を持った人）が取り込むか判断するものになります。
システムが稼働しているソースコードに修正内容をいきなり取り込むのではなく、プルリクエストを通すことで誤った修正を取り込んだり、悪意を持った修正を弾けるようになります。
プルリクエストの目的
プルリクエストはソフトウェアに対する修正を分かりやすく説明するドキュメントです。修正点はソースコードの差分を見れば分かりますが、その意図をすべてくみ取るのは困難です。分かりやすいプルリクエストを書くことで、レビューアーの負担やミスを防げます。
修正した意図が分かれば、もっと良い修正方法が提案されたり、不明点を確認するなどコミュニケーションも活発になるでしょう。
プルリクエストの書き方
プルリクエストにはレビューやフィードバックを行う上で必要十分な情報が盛り込まれていなければなりません。調べれば分かるといった情報も記述しておくことで、レビューコストを低減させます。
- タイトル
- 目的
- 関連する文書やリンク
- 達成できる内容
- 疑問点や不安
- 除外内容
- スケジュール
タイトル
プルリクエストのタイトルは修正内容を一目で分かるような簡潔なものを記述します。もしフィードバックが欲しい場合にはタグを使う他、タイトルの頭に [WIP] （Work in progress）と記述すると言ったルールが設定されている場合もあります。
目的
プルリクエストの目的を記します。プルリクエストは社内（オープンソース・ソフトウェアの場合は全世界）の誰もが読む可能性を考えます。そのため前提知識やこれまでのすべての議論に精通していると考えるのはよくありません。
フィードバックが必要な場合には、具体的にどのようなフィードバックが欲しいのかも記述しましょう。コードの書き方についてか、技術的な観点か、デザインに関するコメントなどです。
特定の個人を議論に参加させたい場合には @ をつけてメンションを飛ばします。GitHubに限らず多くのリポジトリサービスでは @ を使って通知を出せるようになっています。
関連する文書やリンク
ソースコードの修正は何らかのタスクや、Issue（バグ報告など）に関連するものが多いです。そのため、プルリクエストを作成する際には関連する文書やリンクを追加した上で作成すると、レビューアーの補助になります。
具体的な要件が分からない状態では、その修正が適当であるか判断しづらいでしょう。ブランチ名をIssueのIDにしたりする運用としているケースもあります。
達成できる内容
修正内容によって達成できる内容を明記します。多くの場合、この項目は箇条書きになるでしょう。目的のところでは読みやすい文章として書きつつ、この部分ではより明確に端的なリストとして記述します。
関連するタスクに対して、実際の解決法は様々にあるでしょう。この達成できる内容があることで、レビューアーはより最適なレビューができるようになります。
疑問点や不安
もし実装内容や技術的に不安があったり、自分の修正内容に疑問点がある場合にはそれも明記しておきましょう。レビューアーは特にその観点からコードを精査したり、コメントできるでしょう。
疑問点が解消されないままマージされてしまうと、後で不具合につながる可能性があります。プルリクエストはいきなり完璧である必要はなく、コミュニケーションを通じて改善を繰り返しても問題ありません。
除外内容
もし修正によって期待されるであろう改善範囲に食い違いが生じそうであれば、それを明記しておきましょう。システムが複雑化し、一つの修正が様々な範囲に影響を及ぼすようになると、修正内容が別な機能にも及ぶと期待されてしまうことがあります。
これもまた、マージ後の食い違いを防ぐのに必要です。あらかじめ分かっているのであれば、スコープを明確にしておきましょう。
スケジュール
リリーススケジュールなど、あらかじめリリース日程が決まっている場合には、レビューをいつまでに行って欲しいか書いておきましょう。緊急性のある場合には別途チャットなどでレビュー依頼することになるでしょうが、それ以外の場合でもスケジュールを明記しておかないと放置されてしまう可能性があります。
マニュアル作成・ナレッジ共有ツール「NotePM」を無料でお試し！
プルリクエストのサンプル例
##タイトル
物流システムにおける帳票形式のアップデート
##目的
2022年3月より帳票フォーマットが刷新されます。それを受けて、帳票フォーマットを変換する修正を行っています。3月以前であれば、従来通りのフォーマットで出力します。
##関連する文書やリンク
プロジェクト管理の DS-11010 帳票フォーマットの刷新
##達成できる内容
- 2022年3月以前の旧フォーマットでの帳票出力
- 2022年3月以降の新フォーマットでの帳票出力
##疑問点や不安
日付が絡む処理なので、テストはダミーの日付を適用して行っています。システムから単純に出力しただけでは旧フォーマットになってしまうので注意してください。
##除外内容
本修正は物流システムに限定しています。販売管理システムは対象外です。
##スケジュール
2022年3月リリースに間に合わせるため、2月10日までのレビューをお願いします。
NotePM（ノートピーエム） は、Webで簡単にマニュアル作成できて、強力な検索機能でほしい情報をすぐに見つけられるサービスです。さまざまな業界業種に導入されている人気サービスで、大手IT製品レビューサイトでは、とくに『使いやすいさ・導入しやすさ』を高く評価されています。
NotePMの特徴
- マニュアル作成、バージョン管理、社外メンバー共有
- 強力な検索機能。PDFやExcelの中身も全文検索
- 社内FAQ・質問箱・社内ポータルとしても活用できる
- 銀行、大学も導入している高度なセキュリティ。安全に情報共有できる
URL: https://notepm.jp/
