generic-migration

汎用プラグイン移行の手順

破壊的変更が含まれる可能性のある上流リリースへプラグインを移行するための、体系的な手順です。ここに記載する内容はすべてフレームワークに依存しません。製品名、バージョン番号、API 識別子は含みません。上流プロジェクトに変更履歴やリリースノートがある場合は、必ず併せて参照してください。

0. 基本ルール

• 何も確認せずに移行しないでください。 移行元から移行先までの経路に含まれるすべてのバージョンの上流変更履歴を読んでいない場合は、推測に頼ることになります。
• 編集前に棚卸ししてください。 プラグインが何に依存しているかを書き出しておけば、クラッシュが起きるたびに問題を発見する事態を避けられます。
• 一度に変更するレイヤーは一つだけにしてください。 新しい環境で問題がないと確認できるまでは、古い環境も実行可能な状態に保ってください（並行インストール、別々のデータディレクトリなど）。

1. 依存箇所を棚卸しする

コードに手を加える前に、プラグインを読み取り専用でスキャンし、ホストとの依存箇所をすべて記録してください。一般的な依存箇所のチェックリストは次のとおりです。

1. マニフェスト／メタデータ — 宣言された互換性の範囲、エントリーポイント、権限、プラグインが要求する機能。
2. ホスト API のインポート — ホストまたはその SDK からインポートされるすべてのモジュール、シンボル、型。読み込み時と呼び出し時のどちらで使用されるかを記録します。
3. ライフサイクルとイベント — アクティベーションフック、イベントの購読、破棄処理。
4. サービスと RPC — プラグインが利用または公開するサービス、プロセス間通信やリクエスト／レスポンスのチャネル、およびそのペイロードの形状。
5. UI への追加要素 — コマンド、ビュー、パネル、メニュー、テーマ、キーバインド。
6. 永続化 — プラグインが読み書きするファイル、データベース、キーと値のストア。スキーマのバージョンや移行コードも含みます。
7. プロセスと I/O の境界 — 起動するサブプロセス、ソケット、パイプ、ホストが生成した出力（ログ、CLI テキスト、シリアライズされた状態）のパーサー。
8. 設定 — 読み書きする設定キー、プラグインが依存するデフォルト値、およびそれらのキーに関するユーザー向けドキュメント。
9. 依存関係 — ホストと共有するパッケージ（インスタンスの重複リスク）、ピア依存関係の範囲、実行時バージョンの下限。

項目ごとに、ファイルと行番号、具体的な依存内容、確信度を記録してください。「該当なし」という結果に意味があるのは、何をスキャンし、何を除外できなかったかを明記した場合に限ります。

2. 移行経路の両端だけでなく、全体を確認する

リリース経路をまたぐ変更は相互に影響します。途中のリリースもすべて確認し、変更内容と差分を調べたうえで、最終状態の表を作成してください。

• 中間バージョンで削除されたフィールドが後のバージョンで復元された場合、最終的な変更はありません。これを「移行」して取り除いてはいけません。
• 名前の変更が A → B → C のように二段階で行われた場合は、A → C へ直接移行します。
• デフォルト値、順序、タイミングなどの動作変更も、API の削除と同様に破壊的な変更です。明示的に列挙してください。

上流の変更はそれぞれ、破壊的（編集が必要）、動作上の変更（再確認が必要）、追加的（任意）、または参考情報に分類します。

3. 対応関係を整理してから編集する

棚卸しで見つかった項目（§1）を、移行経路の変更内容（§2）に一つずつ対応付けます。その後で初めて、次の順に編集してください。

1. まずマニフェストと互換性の範囲を変更します。ホストが、ほかの修正を読み込む前に読み込みを拒否する可能性があります。
2. ホスト API の範囲：名前の変更、削除、シグネチャの変更。
3. ライフサイクル、イベント、サービス。
4. 永続化の移行（ユーザーの唯一のコピーを決して変更しないでください。初回実行時にバックアップを作成してから移行するか、安全側に倒して処理を停止します）。
5. UI と設定。
6. 依存関係の整合：共有パッケージがホストのインスタンスに解決されるようにします。インストール済みのツリーに重複がないか確認してください。

4. レイヤーごとに検証する

まずは低コストのレイヤーから始めます。次のレイヤーに進む前に、各レイヤーに合格する必要があります。

1. 静的検証：型チェック、リント、プラグイン独自の単体テスト。
2. インストール時：ホストがマニフェストを受け入れ、警告を出さずにプラグインを読み込むこと。
3. コールドスタート：プラグインを有効にした状態で、実際のホストプロセスが起動すること。クラッシュだけでなく、非推奨やフォールバックに関する警告がログにないか確認します。
4. 機能プローブ：主要な機能ごとに、実際のエンドツーエンドの経路を1つずつ確認します。移行しなかった機能も含めてください（動作のひそかな変化はそこに潜んでいます）。
5. データ：実際に永続化されたデータのコピーを移行し、往復変換とダウングレード時の動作を確認します。
6. ロールバックのリハーサル：元に戻せることを実証します。移行済みデータに対して旧バージョンを再インストールし、引き続き動作すること、または復元手段があることを確認します。

5. 規律と落とし穴

• 削除された動作を自分で再実装するより、ホストが文書化している代替手段を優先してください。
• 「型チェックに合格した」は、検証の始まりであって終わりではないと考えてください。
• 非推奨でも動作する機能は、いずれ失敗する予定のものです。スコープ外であっても記録してください。
• 変更の意味が明確でない場合は、対象タグのアップストリームソースを読み、一行の変更履歴からデータ形式を推測しないでください。
• 変更した内容、理由、検証した内容を、移行ログに記録してください。それが、ほかの人が移行を信頼するための成果物になります。