flutter-upgrade-3-47

このスキルは、Flutterプロジェクトを Flutter 3.47 へ安全かつスムーズに追従・アップグレードするための専用スキルです。すでにローカル環境/FVMが 3.47 に更新済みの場合でも、未更新の場合でもスムーズに対応します。

📚 一次情報・公式リファレンス (Reference Links)

アップグレード作業時に参照すべき公式の重要情報源一覧です：

• 📢 What's New in Flutter 3.47 (Official Blog): https://flutter.dev/blog/whats-new-in-flutter-3-47 (または https://blog.flutter.dev/whats-new-in-flutter-3-47)
• 📝 Flutter 3.47.0 Release Notes: https://docs.flutter.dev/release/release-notes/release-notes-3.47.0
• ⚠️ Flutter Breaking Changes: https://docs.flutter.dev/release/breaking-changes
• 📰 Flutter Release Announcements Category: https://flutter.dev/blog?category=release
• 🎯 Dart Blog: https://dart.dev/blog

🎯 目的と概要

Flutter 3.47（2026年8月リリース）へのプロジェクト追従を以下のステップで自動化・サポートします。

1. 環境確認 & Flutter SDK バージョンの昇格/確認:

- すでに 3.47.x の場合: SDK更新処理をスキップ。 - 未更新の場合: FVM (.fvmrc 更新 + fvm use 3.47.0) または flutter upgrade で 3.47.0 へ昇格。

1. pubspec.yaml / melos の environment バージョン下限引き上げ (caret指定):

- 通常プロジェクト: pubspec.yaml の environment: (sdk: "^3.13.0", flutter: "^3.47.0") を更新。 - Melos モノレポ: ルート pubspec.yaml の melos.bootstrap.environment を更新し、melos bs で配下全パッケージへ一括自動適用。

1. flutter create . の 3.47 最新テンプレート追従: AGP 9 / Built-in Kotlin, Android/iOS/Web 構成の更新。
2. 自動修復 (dart fix --apply): 機械的なコード修正の適用。
3. オプトイン移行 (migratedesignwidgets) の対話的提案: SDKから分離された materialui / cupertinoui パッケージ移行の選択。
4. 動作変化・ランタイム注意点のチェック報告: コンパイルエラーにならなくても動作・描画・アクセシビリティが変わる懸念事項の提示。
5. Draft PR起票・コミットフォーマット遵守: git-commit-formatter および gh CLIを用いた安全な起票。

🚀 実行手順ワークフロー

Step 1: 環境確認・Flutter SDK 昇格 / FVM 切り替え & Draft PR作成

1. 現在の Flutter SDK バージョンおよび FVM 設定の確認:

- プロジェクトルートの .fvmrc や .fvm/fvm_config.json の有無を確認。 - flutter --version (FVM使用時は fvm flutter --version) を実行。

1. バージョン昇格 / スキップの分岐処理:

- ケース A: すでに Flutter 3.47.x に更新済みの場合: - 「Flutter SDK はすでに 3.47.x に達しています」とログ・報告を出力し、SDK更新処理はスキップ。 - ケース B: まだ旧バージョン（例: 3.44 や 3.41 等）の場合: - FVM利用時: .fvmrc のバージョン指定を "3.47.0" に書き換え、fvm use 3.47.0 (または fvm install 3.47.0) を実行。 - グローバル Flutter 利用時: ユーザーに状況を案内した上で flutter upgrade を実行して 3.47.0 へアップデート（または FVM 導入を提案）。

1. Gitブランチの作成:

- feature/mono/3-47-flutter-upgrade ブランチを作成して切替。

1. Draft PR の起票:

- 空コミット git commit --allow-empty -m "chore: start Flutter 3.47 upgrade" を作成し, push。 - env -u GITHUBTOKEN -u GHTOKEN gh pr create --draft --title "chore: upgrade Flutter to 3.47" --body "Draft PR for Flutter 3.47 upgrade" で PR を起票。

Step 2: environment バージョン更新 & flutter create . 最新テンプレート追従

1. 通常プロジェクトの場合:

- pubspec.yaml の environment 指定を caret (^) 形式で更新。 ``yaml environment: sdk: "^3.13.0" # 最新Dart言語機能を活かせるよう引き上げ flutter: "^3.47.0" ``

1. モノレポ (Melos) プロジェクトの場合:

- ルートの pubspec.yaml (または melos.yaml) の melos.bootstrap.environment を更新： ``yaml melos: bootstrap: environment: sdk: "^3.13.0" flutter: "^3.47.0" ` - その後 melos bs (melos bootstrap) を実行して、全サブパッケージの environment` 指定を一括更新・ブートストラップ。

1. flutter create . テンプレート生成と差分比較:

- 一時ディレクトリにて flutter create --org com.example temp_app を実行（FVM使用時は fvm flutter create ...）。 - 既存プロジェクトの設定ファイルとテンプレートを比較し、以下の差分を反映：

1. Android 構成:

- AGP 9+ & Built-in Kotlin への移行: android/build.gradle や android/settings.gradle の Gradle プラグイン定義、Kotlin 設定を Built-in Kotlin 仕様にアップグレード。

1. iOS / macOS 構成:

- Xcode 26 / iOS 26 シミュレータ互換の設定、Podfile のプラットフォームバージョン指定の確認。

1. Web 構成:

- HTML レンダラー参照の削除（CanvasKit / WebAssembly への完全移行）、フォントフォールバックサービスの更新。

Step 3: 自動修復 & 依存関係の更新

1. flutter pub get （Melosの場合は melos bs または melos exec -- flutter pub get）を実行。
2. dart fix --apply を実行して、機械的なコード修正を全適用。

Step 4: オプトイン/ベータ機能移行 (migratedesignwidgets) の対話選択

ユーザーへ ask_question または対話にて、以下のオプトイン移行機能の適用可否をヒアリングします。

📌 オプトインコード: dart fix --apply --code=migratedesignwidgets

• 概要:

- Flutter 3.47 より、Material / Cupertino デザインシステムが Flutter SDK コアから独立パッケージ (materialui, cupertinoui) へ切り離し開始。 - コマンドを実行すると、pubspec.yaml に materialui (および cupertinoui) を自動追加し、package:flutter/material.dart 等の import を package:materialui/materialui.dart へ自動書き換えします。

• メリット:

- 今後（2026年秋の次期リリースでコアSDK内デザインライブラリが非推奨化予定）のSDKアップデートへの先回り追従ができる。 - デザインシステム単体での更新や最適化の恩恵を受けられる。

• デメリット・リスク:

- 外部パッケージ依存が追加される。 - まれに pubspec.yaml の自動書き換えに失敗する場合があり、その場合は手動で flutter pub add material_ui を行う必要がある。

• 推奨度: 【推奨 (Recommended)】 （今期のPRで移行を完了しておくことが望ましい）

対話メッセージ例:
「Flutter 3.47 では Material/Cupertino が独立パッケージ (materialui/cupertinoui) に分離されました。今期 PR で dart fix --apply --code=migratedesignwidgets を適用して切り替えを行いますか？」

Step 5: 動作変化の懸念点・不安要素のチェックと提示

コンパイルエラーにならなくても、ランタイム挙動・描画・UIが変わる可能性があるため、以下の項目を重点的にチェックし、報告・手動調整を実施します。

⚠️ 動作変化・注意が必要な箇所一覧 (Flutter 3.47)

Step 6: 静的解析 & テスト検証

1. dart analyze (モノレポの場合は melos run analyze) を実行。

- エラー・警告が 0 件であることを確認。手動修正が必要な場合はコードを修正。

1. flutter test を実行。

- 既存のユニットテスト・ウィジェットテストが全てパスすることを確認。

Step 7: コミット & PR 本文の更新

1. コミット作成:

- git-commit-formatter に従い Conventional Commits 仕様でコミット。 - 例: feat(deps): upgrade flutter to 3.47 and apply migratedesignwidgets

1. PR 本文の更新:

- 以下のテンプレートに基づき、env -u GITHUBTOKEN -u GHTOKEN gh pr edit で PR 本文を更新。

## 🚀 Flutter 3.47 アップグレード対応

### 📚 参考リンク (Reference Links)
- [What's New in Flutter 3.47](https://flutter.dev/blog/whats-new-in-flutter-3-47)
- [Flutter 3.47.0 Release Notes](https://docs.flutter.dev/release/release-notes/release-notes-3.47.0)
- [Flutter Breaking Changes](https://docs.flutter.dev/release/breaking-changes)

### 📋 対応内容
- [x] Flutter SDK 3.47 への追従 (事前に3.47昇格済 / またはFVM・flutter upgradeで昇格)
- [x] `environment` (sdk: `^3.13.0`, flutter: `^3.47.0`) の更新 (Melos時は `melos.bootstrap.environment` 経由)
- [x] `flutter create .` 3.47 テンプレート追従 (AGP 9+, Built-in Kotlin, Android/iOS/Web設定)
- [x] `dart fix --apply` による自動修復 (Melosの場合は `melos bs`)
- [x] オプトイン機能 (`migrate_design_widgets`): [適用済 / 未適用]

### ⚠️ ランタイム動作確認・注意事項
- **OpenGL ES render-to-texture**: テクスチャ表示方向の確認
- **Impeller Desktop**: macOS/Windows/Linux でのフォント描画のビジュアル確認
- **Semantics / アクセシビリティ**: 見出し・スクリーンリーダー挙動の確認
- **IndexedStack**: 非表示タブのフォーカス外れ挙動の確認