状態を持つUIライブラリを、今の利用者を壊さずに小さく直す

## 状態の持ち主を見つけ、認められた場所でだけ状態を変える まず、依頼が影響する状態の所有者、更新境界、公開契約を特定する。不変の状態モデルでは、一貫したスナップショットを通じて読み取り、ライブラリが認める更新コンテキスト内でのみ変更する。ノードやエンティティのハンドルは版付きの参照として扱い、更新境界をまたいで変更可能であるという前提を保持しない。 機能登録、コマンド、変換、リスナーは、文書化されたライフサイクル内に収める。新しい作業には現行の拡張または合成の仕組みを優先しつつ、サポート対象の従来統合経路も維持する。すべての登録に明確な後始末の経路を用意し、既存利用者が引き続き読み込む可能性のあるシリアライズ形式を保つ。 ## 構文を見分ける検索で探し、変更を小さく保つ 変更がimport、呼び出し箇所、型注釈、構造化コードに関係する場合は、構文を認識する検索と書き換えを使う。行単位の正規表現は、複数行の形式を見落としたり、無関係な識別子に一致したりすることがある。広範な書き換えを適用する前に、構文木で候補の一致を確認する。 変更は対象の振る舞いに沿った局所的なものにする。領域固有の名前、無効または処理済みの状態に対するガード節、見通しのよい正常経路を使う。ヘルパーの切り出しは、責務に名前を付けられる場合、または呼び出し側を簡潔にできる場合だけにする。便乗したリファクタリング、デバッグログ、仮の名前、無関係な整形を最終パッチへ混ぜない。 副作用のないファクトリをモジュールスコープに作成する場合は、プロジェクトのツリーシェイキング注釈規約を守り、ファクトリの系統自体を拡張するなら、その規約を強制するルールも更新する。 ## 公開APIの互換性を守り、要素自身のdocumentとwindowを使う 外部コードは、既存の公開名、シグネチャ、振る舞い、シリアライズ済みデータに依存していると考える。追加型APIと省略可能な引数を優先する。互換性を壊す変更が避けられない場合は、廃止する前に旧経路を維持して非推奨とし、現行経路と互換経路の両方を検証する。 APIが影響する、サポート対象のすべての型システムと生成済み宣言面を維持する。ブラウザ向けコードでは、周囲のグローバル値に依存せず、該当するルートまたは要素から、それを所有するdocumentとwindowを取得する。領域を認識する選択、フォーカス、イベント対象、親要素探索のヘルパーを使い、シャドウルートや埋め込みdocumentが誤った環境を暗黙に参照しないようにする。 シリアライズ、リクエスト処理、URL、HTMLやスクリプトの生成物、ファイルシステムのパス、認証、依存関係の変更では、信頼できない入力と、それに最も近い検証ガードを特定する。失敗時に閉じる振る舞いを優先し、ログや成果物に秘密情報を残さず、プロトコルの書き手側と読み手側の両方を検証する。 ## 先に失敗するテストを書き、単体か実ブラウザかを選ぶ 振る舞いの変更やバグ修正では、まず観測可能な不変条件を定義する。最も近い焦点を絞ったテストを追加または更新し、可能であれば実装前に実行して、想定した理由で失敗することを確認する。その条件を満たす最小の変更を行い、焦点を絞ったテストを再実行してから、変更面に必要な検証だけへ範囲を広げる。 実際のレイアウトや選択動作に依存しないロジックには、模擬環境の単体テストを使う。レイアウト、選択、フォーカス、シャドウルート、document間の動作には、実ブラウザテストを使う。エンドツーエンドテストは、ナビゲーション、アプリケーション全体の統合、または稼働中のシステムを必要とするプロトコルに限定する。結果を根拠にする前に、テストが使用する特定の成果物をビルドする。 理由なく、焦点を絞ったテストをリポジトリ全体の広範なコマンドで置き換えない。無関係なテスト群の合格は、変更した境界を証明しない。 ## 終える前に差分を見直し、リリースノートを足す 完了前に、新しく参加した貢献者の視点で差分をレビューする。名前が領域の意味を表していること、エッジケースに明示的なガードがあること、主要経路が読みやすいこと、後始末が完了していること、公開契約が意図せず変わっていないことを確認する。影響を受けたパッケージで必要なフォーマッター、リンター、型チェッカー、APIスナップショットのタスクを実行する。 公開される振る舞いが変わる場合は、リポジトリ所定のリリースノートまたは変更記録を追加する。実装の仕組みではなく、利用者向けの修正または機能を説明する。コミットとプルリクエストの文面には、非公開のセッションリンク、認証情報、内部限定の参照を含めず、変更を裏付ける焦点を絞ったテスト証拠を記録する。