rhdh-plugin-nfs-migration

RHDH プラグインの NFS 移行

レガシーフロントエンドシステムから NFS へ移行する際に、フロントエンドプラグインの拡張機能の構成を管理します。変更を加える前にプラグインがエクスポートする内容を確認し、拡張機能の種類を一つずつ移行します。また、ユーザーが破壊的変更を明示的に承認するまで、レガシーの利用側がコンパイルできる状態を維持します。

まず確認すること

1. プラグインの package.json、src/plugin.ts または src/plugin.tsx、ルート参照、API ファクトリー、エクスポートされたコンポーネント、app-config.dynamic.yaml を読みます。
2. ワークスペース独自の AGENTS.md または CLAUDE.md を読みます。リポジトリのルールは、ここに書かれた内容より優先されます。
3. 編集する前に、見つかった拡張機能をすべてユーザーに一覧で提示します。
4. ファイルを変更する前にブランチとステータスを確認し、コミットされていない作業を保護します。

目的に応じた参照先

目的	読み込んで従うもの
プラグインを NFS に移行する	workflows/migrate-nfs.md
移行したプラグインを RHDH でテストする	workflows/test-nfs-plugin.md
移行前に NFS について説明する	references/overview.md
ページまたは API ファクトリーを移行する	references/migrate-page.md
エンティティタブまたはカードを移行する	references/migrate-entity-content.md
翻訳を移行する	references/migrate-translations.md
RHDH のドロワー、ヘッダー項目、ホームページウィジェットを移行する	references/migrate-rhdh-extensions.md
アプリレベルのラッパーまたはルート要素を移行する	references/migrate-app-level.md
レガシーの動的マウントポイントを拡張機能に対応付ける	references/mount-point-mapping.md
パッケージのエクスポートを更新する	references/package-json.md
NFS 開発用アプリをセットアップまたは更新する	references/app-setup.md
移行を検証する	references/verification.md
RHDH オペレーターの app.extensions または app.routes.bindings にアクセスする	references/operator-config.md
移行に失敗した場合のトラブルシューティング	references/gotchas.md、続いて references/support.md
実際に移行されたプラグインを見つけて参考にする	references/reference-prs.md

対象範囲

• このスキルが担当するのは、拡張機能の構成です。つまり、どの Blueprint がどのレガシー拡張機能に置き換わるか、どこに接続するか、パッケージが何をエクスポートするかを扱います。@backstage/* のバージョン番号は決定しません。
• /rhdh-backstage-upgrade が担当するのは、バージョン番号です。どの Backstage リリースに移行するか、そのリリースの依存関係一式をどう揃えるかを扱います。この移行に必要な Blueprints に対してプラグインの @backstage/* 依存関係が古すぎる場合は、まずこのスキルを名前で呼び出してから、ここに戻ります。
• /backstage-api-changes が担当するのは、初期のアルファ版と現在の GA API の間の NFS API の差分です。削除された NavItemBlueprint、config.schema に代わる configSchema、名前が変更された Blueprint パラメーターなどが対象です。古い NFS API に基づいてすでに移行されたプラグインを移行する場合や、Blueprint パラメーターによって TypeScript エラーが発生する場合は、名前を指定して呼び出します。
• /rhdh-plugin-export が担当するのは、移行したプラグインのエクスポートとパッケージ化です。
• /rhdh-plugin-wiring が担当するのは、dynamic-plugins.yaml の構成生成です。
• /rhdh-local が担当するのは、ローカルの RHDH インスタンスの実行と、プラグイン構成の適用です。
• /rhdh-pr-create が担当するのは、ステージング、コミット、プルリクエストです。変更したファイルはステージングせず、完了時に一覧を提示します。

スキルを名前で呼び出し、会話の中で引き継ぎ内容を説明します。他のスキルのファイルは開かないでください。

不変条件

• NFS は GA ではありません。アルファ版のアプローチをデフォルトとして使用します。NFS は ./alpha に配置し、レガシーのコードはルートのエクスポートにそのまま残します。両方の API を 1 つのインポートパスから使いたい場合にのみ、併置するアプローチを使用します。
• コンポーネントレベルのインポート（useApi、useRouteRef）は @backstage/core-plugin-api のままにし、同じコンポーネントを両方のエクスポートパスで使えるようにします。NFS が提供しないレガシーのコンテキストプロバイダーをコンポーネントで必要とする場合に限り、compatWrapper() を使用します。
• コアのブループリントは @backstage/frontend-plugin-api からインポートします。AppDrawerContentBlueprint や GlobalHeaderMenuItemBlueprint など、RHDH 専用のブループリントは @red-hat-developer-hub/* からインポートします。この 2 つの名前空間を混在させないでください。
• エンティティコンテンツとカードは、プラグインの extensions 配列に直接配置します。createFrontendModule は、別のプラグインを対象にする場合にのみ使用します。翻訳の場合は pluginId: 'app'、ホームページウィジェットの場合は pluginId: 'home' を指定します。
• レガシーエクスポートは引き続き利用可能にします。レガシーの利用側に影響する破壊的変更には、ユーザーの明示的な承認が必要です。
• 利用側のインポートの破損を検出できるよう、プラグインのディレクトリではなくワークスペースのルートから yarn tsc を実行します。
• ここでは、ステージング、コミット、プッシュ、プルリクエストの作成を行わないでください。

完了

見つかったエクステンションとその NFS での相当物、選択したエクスポート方法、変更したファイルとステージングしていないファイル、実行した検証コマンドとその結果、レガシーの利用側へのリスク、およびエクスポート、配線、ローカルテスト、公開の次の手順で呼び出すスキル名を報告します。