分散ジョブ基盤のモノレポを、本物のサービスでテストしながら直す

## ルートからコマンドを実行し、パッケージの種類でチェックを選ぶ 固定されたパッケージマネージャーのラッパーを通し、リポジトリのルートからワークスペースのコマンドを実行する。アプリケーションやコマンドラインツールを起動する前に必要な依存関係をビルドし、ワークスペースのフィルターを使って、影響を受けるパッケージグラフに作業範囲を限定する。 リポジトリの依存関係インストール方針に厳密に従う。インストール前にパッケージ宣言を編集する必要があるなら、レビュー可能なバージョン選択を迂回する追加コマンドを実行せず、宣言を編集する。 パッケージの役割に応じて検証方法を選ぶ。 - アプリケーションと非公開パッケージでは、ビルドだけで正しさを証明できない場合に静的型検査を使う。 - 公開パッケージでは、エクスポートと生成成果物も検査されるように、実際のパッケージビルドを使う。 - 大きな変更、新規ファイル、スキーマ作業、広範なリファクタリングには、ローカルで型検査またはビルド検証を行う。 - 小さな編集は、プロジェクトが明示的に許可している場合に限り、対象を絞った検査と継続的インテグレーションに任せてもよい。 慣れているというだけで広範なビルドを実行しない。変更した層で実際に失敗を検出できる検査を使う。 ## キューやデータベースは、モックでなく本物のサービスでテストする テストはソースと同じ場所に置き、リポジトリが唯一サポートするテストランナーを使う。影響を受けるパッケージまたは一つのテストファイルから始め、ワークスペースで必要な場合に限って先にその依存関係をビルドする。 プロジェクトが使い捨てのサービスコンテナを提供している場合、データベース、キュー、キャッシュをモックに置き換えない。実際の接続オプションとクリーンな状態を提供する分離されたテストヘルパーを、次の用途に使う。 - キューとキャッシュの挙動。 - リレーショナルデータベースのトランザクションとマイグレーション。 - ストレージ境界をまたぐ複合ワークフロー。 純粋関数には軽量な単体テストの境界を残す。インフラストラクチャの挙動には制御された実サービスを優先し、シリアライズ、タイミング、再試行、トランザクションの意味を観察できるようにする。 最終的な読み取り専用のリント検査より前に、フォーマットとリントの自動修正を実行する。静的インポートを優先し、避けられない循環、計測で効果が確認されたコード分割、または真の実行時条件がある場合に限って動的読み込みを使う。 ## 公開パッケージの変更を記録し、共有する依存関係のバージョンをそろえる 公開パッケージまたは連携機能を変更するときは、必ずバージョン付き変更記録を追加する。修正や小さな互換変更ではパッチリリースを既定とし、マイナーリリースはメンテナーに確認し、明示的な承認なしにメジャーリリースを選択してはならない。 公開パッケージに変更がないサーバーのみの挙動には、パッケージのバージョン記録ではなくサーバーの変更ノート機構を使う。 リリース説明はユーザー向けに書く。 - 変更された挙動を最初に示す。 - 可能なら平易な一文にする。 - 内部ツール、キュー、ストレージ、デプロイの名称は省く。 - 実装方法を利点として説明しない。 実行時の型の同一性が依存する場合、意図して共有している依存関係はワークスペース全体で一つの厳密なバージョンに保つ。そのような依存関係を追加する前に既存の固定値を見つけ、完全に一致させる。範囲指定や並行する複数バージョンがあると、あるパッケージのスキーマが別のパッケージの利用側と互換性を失う可能性がある。 ## ジョブが通る道すじを先に追い、各層の役割を勝手に動かさない 編集する前にリクエスト経路を理解する。 1. 外部リクエストがAPIとダッシュボードアプリケーションに入る。 2. サービスが意図を検証し、実行ライフサイクルエンジンを呼び出す。 3. エンジンが状態を永続化し、処理をキューに入れる。 4. スーパーバイザーが処理を引き受け、分離された実行を管理する。 5. 結果がライフサイクルエンジンを通って戻る。 6. トランザクション状態と分析イベントがそれぞれ別のストアへ流れる。 公開SDK、コマンドラインツール、共有型、ビルド拡張、クライアントフック、キューワーカー、データベース、分析、スケジューリング、実行エンジンは、宣言されたパッケージに置く。エクスポート契約で必要なら、公開共有型を広いパッケージルートではなく、サポート対象のサブパスからインポートする。 都合を理由に、これらの層をまたいで責務を移動しない。スケジューリング、キューイング、実行、永続化を変更するときは、状態遷移と失敗経路の全体を考慮しなければならない。 ## 廃止した実行エンジンを戻さず、古いクライアントはエラーできちんと断る 古いエンジンが廃止された後では、過去のディレクトリ名や互換性用の列挙型が残っていても、そのエンジンが今も動作している証拠にはならない。現在のアーキテクチャ文書と有効なパッケージグラフを正本として扱う。 古いブランチやリクエストを満たすために、廃止済みの経路を決して再導入しない。互換性処理が旧バージョンを認識するのは、クライアントエラーとして拒否するか、正常に終了させるためだけでよい。存在しない実行コードへ処理を振り分けたり、想定内の拒否をサーバー障害に変えたりしてはならない。 互換性の挙動を変更する前に、次を行う。 - 有効なエンジン選択を追跡する。 - 旧式のクライアントを識別する方法を確認する。 - 明確なエラーの意味を保つ。 - 現在の経路と旧バージョンの拒否の両方にテストを追加する。 バージョン別SDKガイダンスと生成されたエージェントルールは、それぞれ専用の保守工程で扱う。タスクに明示的に含まれていない限り、配布済みの指示一式を更新しない。 ## 今の公開SDKでタスクを書き、SDKが変わったら説明文書も直す 永続的なタスクは現在の公開SDKエントリーポイントを通じて定義する。旧式のバージョンサブパスをインポートしたり、非推奨のジョブ定義APIを復活させたりしない。 タスク定義には次を含める。 - 安定した識別子。 - 型付けされた入力契約。 - 一つの非同期実行関数。 - 無効な入力に対する明示的なエラー。 - べき等な挙動、または副作用に対して文書化された再試行境界。 コマンドラインパッケージに由来する場合でも、顧客の実行イメージに組み込まれるコードは公開実行時コードとして扱う。パッケージのエクスポート、組み込まれる依存関係、コンテナの挙動をまとめて検証する。 SDK契約を変更するときは、公開文書と例も更新する。製品文書は指定されたサイトに置き、そのサイト固有のフォーマット規則とナビゲーション規則に従う。 ## ローカルのビルドで本物のタスクを最後まで動かして確かめる 保守されている参照プロジェクトを使い、SDKと基盤の変更をローカルビルドに対してテストする。誤ってリリース済みパッケージをテストしないよう、参照プロジェクトをワークスペースのパッケージにリンクする。 次の順序でフローを実行する。 1. 必要なストレージサービスとキューサービスを起動する。 2. データベースのマイグレーションを適用し、参照用の組織とプロジェクトにシードデータを投入する。 3. SDK、コマンドラインツール、影響を受けるパッケージをビルドする。 4. APIアプリケーションをバックグラウンドで起動し、ヘルスエンドポイントを確認する。 5. リンクした参照プロジェクトからローカルタスクワーカーを起動する。 6. ワーカーの準備完了を示す明示的な信号を待つ。 7. サポート対象の制御インターフェースを通じて代表的なタスクを起動する。 8. 期待する終端状態が現れるまで実行をポーリングまたは一覧表示する。 9. 返された結果と永続化された実行状態を調べる。 コンパイルだけでエンドツーエンドの成功を報告しない。証拠としてコマンド出力または実行識別子を保存し、検証が終わったらバックグラウンドプロセスを停止する。 ## イメージはマルチプラットフォーム用で固定し、デバッグの目印はマージ前に外す コンテナイメージはアーキテクチャ固有のイメージダイジェストではなく、マルチプラットフォームのインデックスダイジェストに固定する。イメージのプラットフォーム中立なリリースページからダイジェストを選び、開発環境と継続的インテグレーションで正しいアーキテクチャが解決されるようにする。 分散フローの開発中は、構造化されたデバッグ用の手がかりを使う。 - 状態遷移、キュー境界、外部呼び出しにマーカーを追加する。 - 登録済みのアプリケーション名前空間だけを使い、承認なしに新しい名前空間を作らない。 - バグを再現する前に既存のトレースを消去する。 - 上限とカーソルによるページ分割を指定して照会する。 - 調査中は一時マーカーを開発ブランチに残す。 - マージ前にマーカーとインポートを取り除く。 ブランチ上にあるというだけで、認識済みの一時的な計測をレビュー担当者が指摘してはならない。本番環境に到達しないことと、完了工程に除去手順が含まれていることを確認すべきである。 ## 変更に合うチェックだけを行い、何をして何を省いたかを報告する 引き継ぎの前に、変更されたファイル一式をすべて調べ、該当するゲートだけを実行する。 - フォーマッター、リント修正、読み取り専用リント。 - アプリケーションと非公開パッケージの型検査。 - 公開パッケージの実ビルド。 - 使い捨てサービスコンテナを使った対象限定テスト。 - 適切な境界でのパッケージ変更記録またはサーバーノート。 - 共有依存関係の厳密なバージョン固定。 - ルーティングを変更した場合の現行エンジンと旧バージョンのテスト。 - イメージ参照を変更した場合のマルチプラットフォームイメージダイジェスト。 - SDKまたは実行時の挙動を変更した場合の、リンクされた参照プロジェクトによる実行。 - マージ前の一時デバッグ計測の除去。 何を実行し、何が合格し、どのゲートをどの理由で意図的に省略したかを報告する。観察できない弱い検査を根拠に、実行時、パッケージ、コンテナが正しいと主張しない。