コンテキスト: GitHub などを利用したチーム開発を想定する。OSS開発に対するコントリビューションの話ではない。

よくあるパターンとして、Pull Request を読んでも変更の背景などがよくわからない、ということが多くなってきて、それの対処として Pull Request の説明を書きましょう、となり、それをある程度強制させるためのテンプレートが欲しくなる。

が、世の中のテンプレート例などを見ると、重厚すぎると感じることが多い。必要よりも多すぎると、書くのが大変すぎて疲弊するか、めんどくさくなって形骸化する。なので、本当に必要なものだけを書く、そのための補助をするテンプレートになっているべきだと思う。過ぎたるは及ばざるが如し。

Pull Request の説明に書くことを強制すべきでないもの

Pull Request というのは、変更・修正であり、コードの差分である。差分ではなく最終的な状態に対する説明は、Pull Request の説明ではなく、それ以外の適切な場所に書き、リンクを貼るだけのほうが良いだろう。

以下、例をあげる:
・ビジネス上の仕様 ... 仕様書
・アルゴリズムの説明 ... コードコメント
・最終的な設計の方針 ... Design Doc / Architecture Decision Records

これらを常に書くべき、という主張をしたいわけではない。書くならPRの説明ではなく、ストック情報として後から辿りやすい場所に残しておくべきだ。

また、そもそも変更したいビジネス/技術的な背景・目的は Issue に書けるものが多い。

Pull Request の説明に書くべきもの

最終的な状態はストック情報にするべき、とすると、Pull Request の説明には、変更・修正にまつわるものを書くべきである。

たとえば、設計AからBに変更したとき、Bの設計方針については必要なら Design Doc を書けばよいが、なぜAの設計を変更してBにしたのか、という点は Pull Request に紐付いている。同じように、バグ修正であれば、なぜもとのコードがバグっていて、この修正でなぜ正しくなるのか、という点は Pull Request の説明に書くべきだろう。

この変更する間で迷ったこと、なども有用な情報だろう。将来的にストック情報としてすべてを残すのは難しいが、この瞬間で共有しておくことでよりよいコードを導いたり、レビュイー・レビュワーの学びにつながる。

テンプレート化は難しい...

ここまで書いてきて、正直、Pull Request の説明をテンプレート化するのは難しいと思ってしまった。ほぼ must と言えるのは、「変更・修正の背景/目的、または、それが書かれている Issue へのリンク」だけだと思う。それくらいはテンプレートなどなくても書くべきだ (といいつつ自分はよく no description で PR 出してしまうので反省せねば...)

必ず書くべきもの、ではなく、書くと有用かもしれないもの、をリスト化しておくと、PRを出す段で「これを書くといいかも」と気づけて便利かもしれない？

- Design Doc, その他ストック情報へのリンク
- (Issue には書いていない) 技術的な変更などの背景
- PR を出すまでの間に調査したり考えたこと
- 他の方法、

... いずれもテンプレートとして用意するほどのものでもないかも。。。

とりあえず、これから自分で Pull Request を出すときには、こういった「ストック情報としては書かないような、今回の変更・差分に関する情報」を意識して書くようにしてみたい。

締まりのない感じになってしまったが、過去に自分が書いた Pull Request に関する記事を貼って終わりにする。