tderoussel/ship-gate

Ship gate

ここにあるすべてのルールは、一見正しく見えるチェックが誤って合格したという経験に基づいています。主張をする前にゲートを実行してください。後から実行しても意味がありません。

スタックに合わせて具体的な内容は調整してください。重要なのは「この主張が偽になる条件は何か？」という形です。これはどのスタックにも応用可能な部分です。

主張のルール

本番環境に関する主張は、本番環境に対してクエリを実行しなければならない。

テストが通ったことは本番環境ではありません。PR のマージは本番環境ではありません。デプロイが成功したことも本番環境ではありません。それらはすべて、主張しているシステムとは別のシステムに関する主張です。

結果を人間が目視確認していなければ、「検証済み」とは言えません。代わりに、実際に何を確認したのかを言いましょう。

デプロイ検証

• 実際にデプロイをトリガーするものを把握する。 Git 連携ホストでは、CLI の呼び出しではなくプッシュがトリガーです。CLI でデプロイした場合、プロジェクトがプッッシュでデプロイする設定になっていると、ユーザーが受け取るビルドとは異なるビルドが生成されます。
• プロジェクトを所有するアカウントを確認する。 ローカルにログインした CLI が、本番プロジェクトを所有していない個人アカウントで認証されている場合があります。その場合、すべてのコマンドが間違ったターゲットに対して静かに成功します。
• デプロイされた SHA に対するコミットステータスを確認する。ダッシュボードを一目見ただけでは不十分です。
• 現在の本番環境のデプロイを確認すること。READY 状態のデプロイが複数存在することがあります。
• Edge/サーバーレス関数はアプリとは別にデプロイされる。 PR をマージしても Edge 関数はデプロイされません。バージョンを明示的に確認してください。
• クライアントのみの変更では、関数のデプロイは不要な場合があります。来ることのないデプロイを待ってはいけません。
• バージョンを主張する前に、ライブマニフェストを再取得してください。並行作業によってバージョンが下書きされることがあります。

CI 検証

• すべての必須コンテキストに対してゲートを適用し、最初の緑だけを見ない。
• パイプされたコマンドをゲートに使わないこと。 some-check | tail は tail の終了コードを報告するため、実際の失敗を隠蔽します。PIPESTATUS がないシェル（zsh は bash と異なります）では、これを間違えやすいです。コマンド自身のステータスを確認してください。
• steps: 0 はジョブが一度も実行されなかったことを意味し、合格ではない。 Checks API は、何も仕事をしなかったジョブに対して結論を報告することがあります。
• ステップなしで不自然に速い失敗は、通常 課金または権限の問題であり、YAML の問題ではありません。
• 失敗したジョブだけを再実行すると、ブランチの古いスナップショットを再実行することになります。最初にブランチを更新し、その後に再実行してください。
• チェックリストには、作成されなかったジョブは含まれない。 失敗がないことは合格の証拠にはなりません。
• gh pr create では明示的な --base が必要です。その周りにチェーンされたヒアドキュメントは静かに失敗することがあります。

型とリンターのゲート

• 大規模な TypeScript プロジェクトでは Node.js のヒープサイズを増やす必要がある場合があります。増やさないと tsc がコードエラーのように見える形でクラッシュします。
• 型チェッカーとリンターが実際にカバーするディレクトリを把握する。 Edge 関数のディレクトリは、両方から除外されていることがよくあります。別のランタイム上で動作する場合は、そのランタイムの独自のチェッカーで確認してください。テストジョブは型ゲートではありません。
• ワークツリーまたはクリーンチェックアウトでビルドし、未コミットのドリフトがある作業ディレクトリではビルドしない。

データベース

• 決して本番環境に対してカジュアルにスキーマをプッシュしたりマイグレーションを実行しないでください。プロジェクトが選択したレビュー済みのパスを通じて、一度だけスキーマを適用します。
• 新しいストアドプロシージャは、実際のデータベースに対して呼び出してから信頼する。 モックは、実際の型と実際の曖昧性でのみ現れる実行時エラーを隠します。
• テストスイートがデータベースをグローバルにモックしている場合、単体テストがパスしてもデータベースについては何も証明できない。
• トリガー管理カラムでは比較と設定を行わないでください。トリガーが書き込みの下で値を変更します。
• マージする前に、変更の影響範囲を本番データに対して測定する。 ローカルシードに対して狭く見えるフィルターが、実際の行に対してはまったく異なる割合にマッチすることがあります。

環境の罠

• マシンのタイムゾーンを決して仮定せず、date を実行する。 日付依存のテストはオフセットで失敗し、その失敗はコードのバグのように見えます。
• Git の identity が設定されていないと、デプロイがブロックされ、無関係なネットワークエラーのように見えることがあります。
• ホスト環境変数はインライン代入ではなくファイルから設定してください。シェルや CLI が末尾の改行を埋め込んで、値を目に見えない形で壊すことがあります。
• スケジュールジョブの成功はジョブの効果の成功ではありません。ランナーが succeeded を報告するのは呼び出しが戻ったことを意味し、作業が行われたことではありません。効果を検証してください。

出力

各ゲートを PASS（証拠） または NOT CHECKED（理由） として記述してください。

実行していないゲートがあれば、そのことを暗に示すような表現は決して使わないでください。いずれかのゲートが失敗した、またはチェックされていない場合は、変更が検証されていないことを明確に述べてください。主張を差し控えることが正しい態度です。