stefafafan の fa は3つです

すてにゃんのブログです

Pull Requestのdescriptionに「影響範囲」を書く理由

わたしはWeb系のエンジニアをやっていますが、普段触っているプロダクトたちはPull Requestのテンプレ*1として以下のような項目が記入されています。

## 解決したい課題

## やったこと

## 影響範囲

## 確認方法

今回はこの「影響範囲」について何故書くと良いと思うのかについて言語化を試みます。

どういう変化が起きると想定しているのかが伝わる

新しい機能をこれからリリースするぞというPull Requestを作る際に、実際にそのPull Requestをマージしてリリースした瞬間からユーザにお披露目となるのか、それとも今はまだフィーチャートグルなどで隠しているからこのままリリースしてもユーザ目線では何も変わらないのか。そういうことがひと目でわかると安心してPull RequestをApproveできる。

またPull Requestの作者の書いた「影響範囲」と実際にの差分が揃っていない場合に「意図通りですか」というコミュニケーションもしやすくなる。

どういう想定外な変化が起こり得るのかが伝わる

例えば共通の関数を変更し機能のロジックを調整したいというPull Requestがあるとする。ここで、「この機能のロジックがいまいちなので変えました。影響範囲はこのセクションです」とだけ書いてリリースすると、実は同じ関数を呼び出していた他の箇所のロジックも想定外に変わってしまいロールバックすることになってしまうかもしれない。このようなことがないように、「そのPull Requestの意図とは別の問題が起こり得るか」を先回りにして洗い出しておけるといざ何かがあっても素早く対応できる。

いじっているコンポーネントが他システムと連携するAPIだとどうか。影響範囲はAPI、つまりそのAPIを利用している他のアプリケーションにも影響が出るかもしれない。間違った実装のままリリースすると最悪ケースそれを呼び出している外部のアプリケーションも壊れてしまう。

いじってるコンポーネントが開発環境だとどうか。意図せずチームメンバーの環境が壊れて全員の生産性が落ちてしまうかもしれない。

リファクタリング系のPull Requestの場合「挙動に変化は無いので影響は無いです」と書かれることがある。こちらもあくまでも「影響なしを想定」しているだけであって、実装が間違ってたりテストが足りてなくてバグってることに気づかないときに影響は出る。「挙動の変化が無いことを想定しているが、このコンポーネント・関数を触っているので問題が起きるとしたらここです」という風なことがまとまっていると良い。

書くことによって様々なケースを前もって考慮できるようになる

慣れている開発者であればわざわざ書かなくとも「リリース後に不具合が起きたとすればこのPull Requestのせいだな」とわかるかもしれませんが、それにしてもやはり明確にdescriptionにかかれているほうが親切。影響範囲を書いてる間にも、「あのコンポーネントでもこの関数が呼ばれてたみたいだから確認しておいたほうが良さそうだな」となって同じコードを触ってる他メンバーと会話をして確認ができたり、マージする順番などについて相談したりしやすくなる。

また、「想定する変更」と「想定しない変更」の両方をあらかじめわかっている場合、リリース後に「想定する変更が実際に反映されたこと」「想定しない変更が現れていないこと」の両方をチェックすることができる。

さらにこの両方のケースがわかっているということはそれらに対応したテストケースを増やすこともできる。リリース後に「想定しない変更」が反映されてしまいあたふたするよりは、そうはならないことを確約してくれるテストケースを書くことに時間をかけたほうが良い。

おわり

というわけでPull Requestのdescriptionの「影響範囲」という項目を書く理由についてまとめてみました。みなさまもご参考ください。