verifying-production-changes

本番環境への変更を検証する

マージされたからといってデプロイ済みとは限らず、デプロイ済みだからといって検証済みとは限りません。

デプロイをゲートする

バージョン文字列ではなく、本番環境へのリクエストが処理されるコミット SHA を出力するコマンドを記述してください。取得元は、サービスが公開しているもの（ステータスエンドポイント、ビルド情報ルート、ブートストラップマニフェストなど）で構いません。プラットフォームがインスタンスのリビジョンを直接報告する場合は、そちらを優先することを明記してください。次に、サービスのリポジトリをクローンしたディレクトリで、次を実行します。

scripts/deploy-gate.sh --target <merged-sha> --baseline <prior-prod-sha> -- <command>

大規模なフリートでは --samples または --clean-polls の値を増やすか、プラットフォームのロールアウトのペースに合わせて --interval と --max-polls を設定してください。ゲートの説明はヘッダーに記載されています。

• 終了コード 0： 最終行の「No stale instance observed across N sampled requests」を、一字一句そのまま記載してください。

• 終了コード 1、rollout-in-progress： 失敗ではなく、オンとオフの件数を添えてロールアウトが進行中であることを報告してください。not-deployed： どのサンプルでも変更が稼働していないことを報告してください。

• 終了コード 2、3、または 5： 呼び出し方法、SHA、またはサンプリングコマンドを修正してから、再実行してください。

• 終了コード 4： ベースラインにすでに対象が含まれているため、このデプロイより前に本番環境で稼働していたリビジョンを確認してください。

• 本番環境で何が稼働しているかに関する主張はすべて、サンプルの範囲に限定してください。「完全にデプロイ済み」や「本番環境はもう古い SHA ではない」とは決して述べないでください。

• スクリプトを実行できない場合は、ヘッダーを読んで、手元のサンプルにそのルールを適用してください。

• すべてのサンプルが対象のコミットを示している場合は、祖先関係の確認が保留中であっても、上記の文を記載してください。

変更後のデータを検証する

一度限りの移行、バックフィル、またはクリーンアップを対象とします。検証は読み取り専用で行います。書き込みモードでタスクを再実行したり、データを修復したりしないでください。不一致を報告してください。

• レポートモードのログを使用してください。 書き込み後に利用できる唯一の変更前データは、ログに記録された行ごとの期待値です。
• 2 つのコホートを確認してください。 変更されるはずの行と、変更されないはずの行です。タスクが必要以上の行に触れたことを検出できるのは、変更されなかったコホートだけです。条件によって差が出る各軸にわたってサンプリングし、レポートで特別扱いされた行（部分処理、スキップ、競合）も含め、読み取り専用クエリで予測値と実際の値を差分比較してください。
• フリート全体に及ぶ不変条件を 1 つ確認してください。 タスクでなくすはずだった対象の数が、現在はゼロであることを確認します。この件数により、サンプルが見逃したすべての行も確認できます。
• レポートの合計値を変更後の件数と照合してください。
• 証拠を明示してください。 レポートと実際の値の一致に加えて不変条件がゼロであれば強い根拠になりますが、行単位の変更前データではありません。削除された行に何が含まれていたかを示す独立した記録がない場合は、その旨を明記してください。どの証拠があるかを述べてください。

デプロイの順序

• あるデプロイを別のデプロイより先に行う必要がある場合、その制約は通常、非対称です。
• どの順序なら安全か、逆の順序では何が壊れるか、問題が自然に解消するかどうかを、PR 本文に記載してください。
• その内容を両方のコードで検証してください。たとえば、どちらの順序にも「対応できる」クライアントでも、条件付きのラベル変更より上流に無条件のフィルターがあると、一方の順序ではシグナルを失うことがあります。
• 古いレンダラーがまだ読み取る行を一度限りのタスクで削除する場合、そのタスクは両方のデプロイが完了するまで実行できず、自然には解消しません。順序を強制する仕組みはないため、順序を記した箇所でその旨を明記してください。