複数ブラウザ向けの拡張機能を、シークレットを漏らさず、保存データを壊さずに直す

## 直す前に、関係する層とその層の決まりを確かめる コードを変更する前に、影響を受けるレイヤーを特定します。対象にはバックグラウンドロジック、ユーザーインターフェース、共有ユーティリティ、ブラウザ宣言、ビルドツール、テスト、保存済み状態のアップグレードがあります。編集前に最も近いレイヤー固有の指示を読みます。ワークフロー自動化ファイルには追加の接続設定やマージキュー規則が含まれることがよくあります。 リポジトリで管理されている実行環境とパッケージマネージャーのラッパーを使用します。設定は指定されたローカル環境ファイルに置き、追跡対象のソースには決して含めません。新しい実装ファイルには現在採用されている型付き言語を優先します。従来の型なしファイルは、依頼された変更によって変換が妥当になるまで維持できます。 ファイルの種類ごとに割り当てられたフォーマッターを使用します。コードフォーマッターは型付きファイルとコンポーネントファイルを担当し、構造化データ用フォーマッターはパッケージデータと設定データを担当します。引き渡し前に、変更ファイルの整形、静的型検査、lint、循環依存検査を実行します。 関数の責務を絞り、早期リターンでネストを減らします。所有関係が明確になる場合にのみ重複ロジックを抽出し、デバッグログやコメントアウトしたコードは残しません。 ## シークレットを手元に置き、依存関係を変えたらポリシーを作り直す API認証情報、監視エンドポイント、テスト用パスワード、署名素材はローカルシークレットとして扱います。文書化したプレースホルダーを用意しますが、実値をコミットしたり、診断ログに機密状態を含めたりしてはいけません。 依存関係の追加、更新、除去はすべてサプライチェーンの変更です。次の手順をすべて完了します。 1. パッケージ宣言とロックファイルを更新します。 2. サポートされているコマンドでロックファイルの重複を解消します。 3. インストールスクリプトの実行を許可するパッケージの許可リストを再計算します。 4. 依存関係によるホストAPIへのアクセスを制限するケイパビリティポリシーを再生成します。 5. サードパーティーの帰属情報を再生成します。 6. 本番用セキュリティポリシーを有効にしてビルドとテストを行います。 生成されたポリシーと帰属情報の変更はすべて同じレビューに含めます。ポリシーを適用しない開発ビルドは迅速な反復に使用できますが、保護された最終ビルドの代わりには決してなりません。ビルドを通すためにポリシーを弱めず、対象プラットフォーム上でプラットフォーム依存のポリシーを再生成します。 ## バックグラウンドのコントローラーを、状態の決まりをはっきりさせて作る バックグラウンドのビジネスロジックとサブシステム間のメッセージ通信にはコントローラーを使用します。保存する各プロパティについて、匿名か、診断用スナップショットや状態ログに安全に含められるか、永続化するか、インターフェースが利用するかを宣言します。 次の状態規則に従います。 - 共有される可変のデフォルトオブジェクトではなく、新しいオブジェクトを返すデフォルト状態ファクトリーをエクスポートします。 - コンストラクターの依存関係は位置引数ではなく、名前付きの単一オプションバッグで受け取ります。 - 追加、除去、承認、却下などのドメイン操作をモデル化し、汎用的なフィールドセッターは避けます。 - 必須の状態だけを保存し、件数、フラグ、射影はエクスポートされたセレクターで導出します。 - 状態を更新する前にアクションの入力を検証します。 - タイマー、購読、リスナー、メッセージチャネルのライフサイクルクリーンアップを実装してから、親のクリーンアップに処理を委譲します。 コントローラーのソース、型、同じ場所に置くテスト、登録、影響を受けるセレクターを同期させます。状態の構造を変更する場合は、番号付きのアップグレード手順も必要です。 ## コードを持ち主の層に置き、つながるファイルも一緒に直す 再利用可能なインターフェースコンポーネントは、そのスタイル、型、テスト、ストーリー、文書、パブリックエクスポートとともに配置します。ページ専用コンポーネントはページレイヤーに、バックグラウンド専用ヘルパーはバックグラウンドコードとともに配置し、本当に共有するユーティリティ、定数、型は共有モジュールに配置します。 動作を変更するときは、直接結合しているファイルを確認します。 - コントローラーの変更では、テスト、型、登録、状態アップグレードも必要になる場合があります。 - コンポーネントのプロパティ変更では、テスト、ストーリー、スタイル、文書、エクスポートも必要になる場合があります。 - グローバル状態の変更では、セレクターとそれを利用するコンポーネントも必要になる場合があります。 - ビルドやブラウザ宣言の変更では、対象固有のフィクスチャとエンドツーエンドの網羅も必要になる場合があります。 所有者を選ぶことを避けるためだけに共有ロジックを複製してはいけません。最も範囲の狭い共通レイヤーへ移し、必要に応じて依存性注入を使い、例外リストの拡大を受け入れずに循環インポートを解消します。 ## ブラウザごと・機能フラグごとに、ビルドとテストを分ける サポートするブラウザ宣言の生成方法ごとに、個別のビルド経路とテスト経路を維持します。永続的なバックグラウンドページとサービスワーカーの違い、権限モデル、名前空間の可用性などを考慮します。 共有コードではクロスブラウザAPI抽象化を使用します。避けられない対象間の違いは、機能全体に条件を散在させず、小さな互換性レイヤーに隔離します。 機能フラグは明示的なビルド入力にします。 - 再現可能な開発には、文書化されたローカル設定を使用します。 - 隔離された実験には、単一コマンドの環境上書きを使用します。 - リモートフラグのテストシナリオに限り、ローカル宣言の上書きを使用します。 - リリースする対象とフラグの組み合わせをそのままビルドしてテストします。 ユーザーがブラウザを指定していない場合は、プロジェクトで文書化されたデフォルト対象を使用します。依頼で対象が指定されている場合は、別のビルドから互換性を推測せず、それに対応する開発、本番、エンドツーエンド用コマンドを選択します。 ## 画面のコンポーネントを作り、最適化は測ってからにする 関数コンポーネントとフックを使用し、境界でプロパティを分割代入し、ローカル専用の状態はローカルに保ちます。共有状態レイヤーは機能をまたぐデータだけに使用します。 描画の正確性と性能を保つには、次の規則に従います。 - 動的リストのキーには配列位置ではなく、安定したドメイン識別子を使用します。 - 導出された表示値はエフェクトで状態へコピーせず、描画中に計算します。 - コストの高い並べ替え、絞り込み、集計は、反復作業の負荷が実質的な場合にのみメモ化します。 - 参照の変動が再描画を引き起こす場合は、メモ化した子へ渡すコールバックを安定させます。 - 本当に静的なオブジェクトとスタイルはコンポーネントの外部で定義します。 - 大規模なリストでは、描画コストを測定した後に仮想化を検討します。 入力が不変の場合は、並べ替える前にコピーします。頻繁に描画されるコンポーネントや計算負荷の高いコンポーネントを先にプロファイルし、単純でほとんど描画されないコンポーネントには根拠なくメモ化を追加しないでください。 ## バグはまず失敗するテストで再現し、直してからテストし直す バグの場合は、まず不具合を再現する対象を絞ったテストを追加して失敗を確認し、最小限の修正を実装して成功を確認してから、直接関連する範囲をテストします。単体テストはソースと同じ場所に置き、非公開メソッドではなく外部インターフェースを通して動作をテストします。 サブシステム間の境界には統合テストを使用します。実際のブラウザワークフローにはエンドツーエンドテストを使用し、最初に専用のテスト成果物をビルドします。反復中は高速な未保護ビルドを許容できますが、最終検証では本番用セキュリティポリシーと依頼されたブラウザ対象を使用しなければなりません。 画面での検証が明示的に依頼された場合は、次の手順を実行します。 1. 実際の拡張機能テスト環境を起動します。 2. 操作する前に現在の画面を確認します。 3. ブラウザ操作でユーザーフローを進めます。 4. 証拠としてスクリーンショットまたは最終画面の説明を記録します。 5. 失敗した場合でもテストセッションをクリーンアップします。 必要な画面検証ツールを使用できない場合は、その制限を報告し、コードの確認だけで画面を検証したと主張してはいけません。スナップショットの変更は受け入れる前に確認し、動作の変更が意図された場合にのみスナップショットを更新します。 ## 保存データの形を変えたら、番号付きのアップグレードを書く 永続化した状態の構造を変更するたびに、番号付きのアップグレードを作成します。順序と登録の一貫性を保つため、リポジトリのツールで生成します。 アップグレードは次の要件を満たす必要があります。 - 古い入力、不完全な入力、部分的に破損した入力を適切に受け入れます。 - 呼び出し元の値を変更せず、入力を複製して新しい状態オブジェクトを返します。 - 自身が担当するバージョン範囲とプロパティだけを変換します。 - 移行先のバージョンを明示的に記録します。 - 関係のないユーザーデータを保持します。 代表的な古い状態、欠落フィールド、不正な任意値、冪等性の要件、正確な新しい結果をテストします。アップグレードテストと、アップグレード後の状態を利用するコントローラーまたは機能のテストを両方実行します。 ## エラーを種類で分け、チェックを切らずに直す 環境を変更する前に、最初の対処可能なエラーを読みます。整形、型、依存関係、ケイパビリティポリシー、ブラウザビルド、テストデータ、古い成果物、ポート、循環インポートの失敗に分類してから、その分類に最も限定した診断を実行します。 以前は成功していたテストが変更後に失敗した場合は、実装に退行が生じたのか、期待される動作を意図的に変更したのかを判断します。後者の場合にのみテストを更新し、動作上の理由を文書化します。 エンドツーエンドの失敗では、正しい最新のテストビルドが存在することを確認し、デバッグ情報を使用し、実際に調査している間だけブラウザを起動したままにします。ポリシーの失敗では、宣言された依存関係とホストアクセスからポリシーを再生成し、適用を恒久的に無効化してはいけません。 キャッシュ、ビルド成果物、インストール済みパッケージ、ブラウザデータ、スナップショットは、正確な対象を特定し、再生成が安全だと確認した後にのみ破棄します。トラブルシューティングの最初の手順として広範なクリーンアップを使用してはいけません。 ## Gitのコミット・プッシュ・レビュー依頼は、頼まれた時だけ行う リポジトリ設定を変更したり、破壊的なバージョン管理コマンドを実行したりしてはいけません。ユーザーがその特定の操作を明示的に依頼していない限り、ステージ、コミット、プッシュ、レビュー依頼の作成を行ってはいけません。 承認されている場合は、次の規則に従います。 - 依頼された変更に属するファイルだけをステージします。 - コミット前に変更範囲を整形してテストします。 - リポジトリの構造化コミット規約を使用します。 - プッシュが依頼された場合にのみプッシュします。 - ユーザーが準備完了状態を明示的に依頼していない限り、ドラフトのレビュー依頼を作成します。 - レビューテンプレートに従い、該当しないセクションを完全に非表示にします。 手動テストのセクションには、自動化されたlintやテストコマンドではなく、人間による操作と画面に見える結果を記載します。インターフェースの見た目を変更した場合は変更前後の証拠を含め、明白でない判断を説明し、関連作業をリンクし、必要に応じてユーザー向け変更メモを示します。 レビュー中は、レビュー済みの履歴を書き換えず、フィードバックに回答してフォローアップコミットを追加します。マージ前には、会話の解決、承認、成功した自動処理、リポジトリが求めるsquashタイトルを必須とします。 最後に、変更ファイルの整形、型、循環依存、対象を絞ったテスト、影響を受けるビルド、関連ファイル、文書、依存関係を変更した場合の本番用ケイパビリティポリシー、依頼された場合の実際の画面証拠を、変更規模に応じたチェックリストで確認します。