かつて，僕が所属しているチームではPull Request(以下PR)のフォーマット，特に「どうして変更するのか」「どう変更したのか」といった経緯などの要素があまり充実していなかった。このためエンジニアのみならずデザイナーやプランナーも含めたチーム内の意思疎通を潤滑にするために，適切なテンプレートを作成してそれに従おうというムーブメントがあった。
とはいっても「この形式が最強」みたいなものをインターネットに見出すことができなかったため，とりあえず『考える技術・書く技術』に範を取って「状況(今どうなっている)・複雑化(それを困難にしている新たな状況の出現)・結論(どうする)」というフォーマットを僕が導入してみた。 それ以前はカッチリしたテンプレートがなく，各自で「こういう感じなのでお願いします」という文言を考えていたので，PR作成者の負担を減らす効果をテンプレートに期待していた。
- 作者:バーバラ ミント
- 発売日: 1999/03/01
- メディア: 単行本
しかしながら時が経つにつれてこのテンプレートのほつれがどんどん大きくなっていった。当初の状況説明テンプレートは以下の通りであった。
- 今なにがどうなっている
- (ここを埋める)
- しかしこのままではいけない，なぜなら...
- (ここを埋める)
- したがってこうする
- (ここを埋める)
だがこのフォーマットは以下のように書かれることが多くなっていった。
- 今なにがどうなっている
- これこれこうなっている
- しかしこのままではいけない，なぜなら...
- 困る
- したがってこうする
- 直す
チーム内からもこれでは不十分という声が上がるようになり，このフォーマットではPRの運用が難しいことが分かった。
したがって別のフォーマットを探す必要に迫られていて，これから人に訊いてみたり，ネットで先人の知恵を探そうと思っているところ。
PRフォーマットが生まれるにいたった経緯
もともとPRのテンプレート(.github/PULL_REQUEST_TEMPLATE.md)には「3行まとめ」というコーナーが作られていた。
とはいえ3行まとめ自体の書き方は特に規定がなかったため，PRの作者が実装の子細を書き込んでしまい，レビュワーにとってはあまり意味がないという状態によくなっていた。
このため3行テンプレートに何を書くべきなのかを決めてみることで，よりレビュワーの理解を助け，PRの意図を明確にしようとしたのだ。
さて「何を書くべきか」の基準として，たまたま自分が知っていた『考える技術・書く技術』の3段階の構造を採用した。 これには特に意図はなく，ひとまず使ってみることにする，くらいの意図だった。本にもなっているしこれでいいか，という具合だった。 何を書けばよいか決まっていればPRを作成する側も考えることを減らせるので楽になるだろう，という効果を期待してのことである。
もっとも，僕が「何でも解決できる万能で厳格なテンプレート」という幻想にこだわったというきらいもある。 そこは反省している。
PRはビジネス文書ではない
ところで『考える技術・書く技術』はおおむねビジネス書であり，掲載されている例も会社を飛び交うビジネス文書に即したものが多い。 いま我が社はこういうふうにやってきましたが，この前提を覆すような状況が発生しています，我が社はこうするべきです・・・といったことを具申するためのフォーマットだ。 PRも既存のコードを修正するための文書だから，そのまま転用できるのではないかという魂胆で使ってみることにしたわけだ。
しかしながら，フォーマットは以下のように(再掲)書かれることが多くなり，あまり活用されなくなってしまった。
- 今なにがどうなっている
- これこれこうなっている
- しかしこのままではいけない，なぜなら...
- 困る
- したがってこうする
- 直す
なぜこうなってしまったのかというと，困るからPRを出しているのだから「困る」のは自明だし，PRは修正するためのものだから「直す」のも自明だ。 このフォーマットではPRの動機をうまく切り取れない。もっと適切に動機を切り取れるような，別の角度を探さなくてはならない。
そもそもよく考えてみると，PRはビジネス文書ではないのだ。 ビジネス文書，特により戦略的で方針などを決定するような文書にこのフォーマットは適合している。 だがPRはそういった文書ではない。PRはより具体的にコードを変更するものだし，PRが対象とするスコープもビジネス文書と比べればずっと小さい。 PRは，コード中の特定の機能などを具体的にどう変更するといったことを表現するためのものだ。
したがってこのフォーマットはPRのテンプレートとしては適合しない。ただ，Issueのテンプレートとしては良く使えると思う。
別のフォーマット探し
そういうわけで，PRのテンプレートに使えるフォーマットを新たに探さなければならなくなった。
幸いにもチームメンバーからはここは不要ではないかといった改善の声が上がっている。「経緯と変更だけ分かればよい」といったものや，「解決したい課題と解決案で良いのでは」「受け入れ条件もあると良い」といった具合で，百花繚乱している。 まだ社の外部からの意見をもらっていないので，知見を持ってそうな人に話を訊いてみたり，既存の記事に知見が貯まっていないかを探そうと思っている。
こういうふうにやってるよという意見や知見などあれば教えてください。
