フィーチャーフラグのリリースノート：何を、いつ伝えるか

機能リクエストでループを閉じるという発想は、そのものが出荷されたきれいな瞬間があることを前提にしている。フィーチャーフラグはその瞬間を消し去り、それがフィーチャーフラグのリリースノートのタイミングを難しくしている。コードはマージされ、フラグは存在するが、その後数日から数週間にわたって、その機能は本番環境で稼働していると同時に、それを使いたいであろうほぼ全員、しばしば最初にそれを頼んだ本人にとってさえも、見えない状態になる。早すぎる通知は、まだそこにない機能に相手を出会わせてしまう。遅すぎる通知は、信頼を築くはずだったループを、忘れられたかのように読ませてしまう。

なぜフラグは「出荷したら伝える」という通常の順序を壊すのか

一つの出来事を少なくとも二つに分割してしまうからだ。コードがライブになることと、フラグが特定のアカウントに対して有効になることだ。フィードバックループを閉じるあらゆるプロセスは、この二つが一緒に起こることを前提としている。それはほとんどのリリースでは正しいが、段階的な展開やターゲティング、あるいは緊急停止スイッチとして使われるフラグの裏にあるものすべてについては誤りだ。顧客フィードバックループを閉じるは、changelogのエントリが承認され公開されたまさにその瞬間に依頼者へ伝えることを描いている。そのステップは、エントリの公開と機能が使えるようになることが同じ瞬間である場合のために書かれており、フラグはまさにそれらが同じでない場合なのだ。

誰かにいつ伝えるべきかの本当のルールは何か

フラグがその人のアカウントで有効になった時に伝える。コードがマージされた時でも、フラグが作成された時でもない。この一つのルールが上の表のすべての行をカバーする。なぜなら、依頼者にとって本当に重要な唯一の事実、つまり今この瞬間に行ってそれを使えるかどうかに通知を結びつけているからだ。マージやフラグの作成に結びついた通知は、実際にはエンジニアリングの進捗報告であり、機能を依頼した人が欲しいのは進捗報告ではなく、いつ確認しに行けばいいかを知ることだ。

それは依頼者が早期アクセスや特別なアクセスを必要とすることを意味するのか

必ずしもそうではなく、それを強制すると独自の問題が生まれる。負荷や安定性の理由でフラグが段階的に展開されている場合、単にループを早く閉じるためだけに一つのアカウントを列の先頭に移動させることは、そもそも展開が段階的である理由を損なう。正直な選択肢は、依頼者のアカウントが自然に展開に到達するのを待ってその時に伝えるか、緊急性がそれを正当化するなら、通知を送りたいという副作用としてではなく、展開を所有する誰かの本当の決定として、意図的に早くフラグを与えることだ。

フラグが展開の仕組みではなく緊急停止スイッチだったらどうか

その場合、安全な前提は逆転する。リリースを段階化するためではなく、機能をすばやく無効化できるようにするために作られたフラグは、通常、その機能が作成された時点で完全にライブになることを意図しており、フラグは順序のためではなく安全のために存在する。その場合、デプロイの時点で依頼者に伝えることは正しく、フラグのないどのリリースとも同じだ。フラグの存在は、ループがいつ閉じるかを変えるべきではない運用上の詳細である。重要な区別は、そのフラグが何のためにあるかであり、フラグが存在するかどうかではない。

フラグはフィーチャーフラグのリリースノートが言うべきことを変えるのか

エントリが公開されるタイミングを変えるのであって、内容を変えるのではない。フラグが100%のアカウントで有効になったまさにその瞬間に公開されたエントリは、まさに通常のchangelogエントリのように読める。それでいい。後でそれを見つける読者には、かつてフラグが関わっていたことを知る理由がまったくない。やってはいけないのは、フラグが小さな展開割合でしか有効になっていない間に公開することだ。なぜなら公開のchangelogエントリは、それを読む全員、フラグのないアカウントも含めて、見つけられない機能を探しに行かせてしまうからだ。これは同じ問題のより悪いバージョンであり、一人の依頼者の規模ではなく製品全体の規模で起こる。このタイミングのルールこそが、フィーチャーフラグのリリースノートと通常のエントリとの違いのすべてだ。内容は同じで、動くのは公開日だけだ。リリースノートの書き方は、ここにも当てはまる「何のアクションも不要」という規律を扱っている。読者はそれが自分に当てはまるかどうかを知る必要があり、単にどこかに存在するというだけでは足りない。

プロダクトアップデートメールはフラグ付きの機能を違う扱いにすべきか

そうすべきで、主に書き直すのではなく遅らせることによってだ。プロダクトアップデートメールのテンプレートは、ターゲットを絞った通知と広範なダイジェストを扱っている。フラグ付きの機能は、ターゲットを絞った通知のタイミングを送信前に受信者自身のフラグの状態と照合しなければならないケースであり、それは広範なダイジェストがまったく簡単にはできないことだ。これは、まだ展開の途中にあるものすべてにとってダイジェストが間違ったチャネルである、もう一つの理由でもある。

FAQ

フラグが存在するがまだその人には有効になっていない時、依頼者に機能は「もうすぐです」と伝えるべきか? 本当に近い、実際の日付が付いている場合に限り、それでも控えめに。日付のない「もうすぐ」は、十分な時間が経つと沈黙とまったく同じように読め、これもまた追跡し守らなければならない二つ目の約束を生む。

フラグがループを閉じるのに十分進んでいるかを誰が決めるのか? 通知を所有する人ではなく、展開を所有する誰かだ。展開を持つ人は「100%のアカウント」が目前なのか、まだ数週間先なのかを知っている。ループを閉じるステップを固定のカレンダー日付ではなくその人の状態に結びつけることが、通知を正直に保つ。

永続的なフラグ（決して完全には削除されない）の裏にある機能は、いつか公開のchangelogエントリを得るのか? 得る。その製品にとって「一般提供」が意味するものに到達すればいい。たとえフラグ自体が運用上の理由で永遠にコードに残るとしてもだ。changelogのエントリは読者にとっての利用可能性についてのものであり、その利用可能性がどう実現されているかという実装の詳細についてではない。

フラグが削除され、機能が出荷ではなく打ち切りになったらどうか? それは拒否であり、出荷の通知ではない。そして他のどんな拒否とも同じ配慮に値する。機能リクエストの断り方は、そのメッセージが何を言うべきかを扱っている。正直にループを閉じるということは、時には「ノー」でそれを閉じることを意味する。

フィーチャーフラグのリリースノートは、通常のエントリとは別のテンプレートを必要とするか? テンプレートは変わらず、公開前にゲートとなるステップが一つ増えるだけだ。コードがマージされたことだけでなく、依頼したアカウントに対するフラグの状態を確認し、そのチェックが通るまでエントリを保留する。文言、長さ、FAQの規律など、エントリに関するそれ以外のすべては、他のどのリリースノートとも変わらない。

この記事の技術的な記述は第三者による確認を受けていません。誤りがあればお知らせください。修正します。

changeloopの関連ページ： 開発者向けドキュメント, changelogツール比較