PullRequestには、問題か課題を書く
from PullRequestの手引き
背景・問題
PullRequestに、やったことだけが書かれていて、背景や問題が書かれていないことが多い
こういうPullReqは、後でその機能をなんのためにつけたのか説明できないので、revertしたりリファクタリングしたりするのが難しい
副作用があるとき、そもそも必要なのかどうかが議論できない
解決策
問題 → 解決か
背景 → 提案
のどちらかにそってPullReqを書こう！
説明に論文フォーマットを使う
Why（理由）をいきなりすらすら書くのは難しい
理由を説明する部分を分解して書く方法として「問題/背景 」-> 「解決/提案」という枠組みを使うと簡単
どんな小さい機能提案やバグ修正にも同じ形式が利用できる
上のテンプレートは、どちらもいわゆる技術論文のフォーマットである
論文フォーマットは、機能を説明、提案するのに最も適している
人に頼まれて作っている場合でも、問題や背景は自分で考えて作るべき
英語で言うと「Problem -> Solution」か「Background -> Suggetion」
さらに細かいヒント
バグの修正や問題の改善には
問題 -> 解決の枠組みを使うのがよくて
新機能を提案したいときは
背景 -> 提案 の枠組みを使うとよい
最初は考えていなかったような説明が思いついたらPullRequestの説明をなんども書き直す
例
mdProblems - 問題、解決したい課題
- ex1) 課金導線でユーザーが迷う問題がある
- ex2) アレをコウするとバグる
Solutions - 提案したい機能
- ex1) この方法で課金導線がスムーズになる
- ex2) 問題を解決した
Implementation - どうやって作るのか？
- ex1) ImagesController#showが参考になると思います
- ex2) このワイヤフレームを参考にしてください http://example.com/
- ex3) 指定なし
イシューからはじめよ――知的生産の「シンプルな本質」もやや関係がある
仕事に取り組むには、まず課題の認識がいるし、それを共有してほしい
実装（コード）だけでなく、問題認識や解決策の選定もレビュー対象という事ですね
国の政策の話などで「柵を取り外す前になぜ柵があるのか考えろ」みたいな言葉を目にする
pull requestで問題・課題を明確にするのは、それと同じ
自分以外がrevertの意思決定をできるようにするために書く
機能変更は、他の機能変更と衝突する可能性がある
その時どちらを選ぶか？
「何をやったか」だけでなく、「なぜやるのか？」「元の状態の問題は何か？」を明確にしないと、決められない
常に変更と変更の間に文脈をつなげ続ける
バラバラの機能が集合した一体感の無い、使いづらいアプリケーションになるのを避けるため