Flutter Upgrade 3 47

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 へ昇格。
2. pubspec.yaml / melos の environment バージョン下限引き上げ (caret指定):
   • 通常プロジェクト: pubspec.yaml の environment: (sdk: "^3.13.0", flutter: "^3.47.0") を更新。
   • Melos モノレポ: ルート pubspec.yaml の melos.bootstrap.environment を更新し、melos bs で配下全パッケージへ一括自動適用。
3. flutter create . の 3.47 最新テンプレート追従: AGP 9 / Built-in Kotlin, Android/iOS/Web 構成の更新。
4. 自動修復 (dart fix --apply): 機械的なコード修正の適用。
5. オプトイン移行 (migrate_design_widgets) の対話的提案: SDKから分離された material_ui / cupertino_ui パッケージ移行の選択。
6. 動作変化・ランタイム注意点のチェック報告: コンパイルエラーにならなくても動作・描画・アクセシビリティが変わる懸念事項の提示。
7. 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) を実行。

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

   • ケース 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 導入を提案）。

3. Gitブランチの作成:

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

4. Draft PR の起票:

   • 空コミット git commit --allow-empty -m "chore: start Flutter 3.47 upgrade" を作成し, push。
   • env -u GITHUB_TOKEN -u GH_TOKEN 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 (^) 形式で更新。

     environment:
       sdk: "^3.13.0" # 最新Dart言語機能を活かせるよう引き上げ
       flutter: "^3.47.0"
     

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

   • ルートの pubspec.yaml (または melos.yaml) の melos.bootstrap.environment を更新：

     melos:
       bootstrap:
         environment:
           sdk: "^3.13.0"
           flutter: "^3.47.0"
     

   • その後 melos bs (melos bootstrap) を実行して、全サブパッケージの environment 指定を一括更新・ブートストラップ。

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

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

4. Android 構成:

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

5. iOS / macOS 構成:

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

6. Web 構成:

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

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

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

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

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

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

• 概要:
  • Flutter 3.47 より、Material / Cupertino デザインシステムが Flutter SDK コアから独立パッケージ (material_ui, cupertino_ui) へ切り離し開始。
  • コマンドを実行すると、pubspec.yaml に material_ui (および cupertino_ui) を自動追加し、package:flutter/material.dart 等の import を package:material_ui/material_ui.dart へ自動書き換えします。
• メリット:
  • 今後（2026年秋の次期リリースでコアSDK内デザインライブラリが非推奨化予定）のSDKアップデートへの先回り追従ができる。
  • デザインシステム単体での更新や最適化の恩恵を受けられる。
• デメリット・リスク:
  • 外部パッケージ依存が追加される。
  • まれに pubspec.yaml の自動書き換えに失敗する場合があり、その場合は手動で flutter pub add material_ui を行う必要がある。
• 推奨度: 【推奨 (Recommended)】 （今期のPRで移行を完了しておくことが望ましい）

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

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

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

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

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

1. dart analyze (モノレポの場合は melos run analyze) を実行。
   • エラー・警告が 0 件であることを確認。手動修正が必要な場合はコードを修正。
2. flutter test を実行。
   • 既存のユニットテスト・ウィジェットテストが全てパスすることを確認。

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

1. コミット作成:
   • git-commit-formatter に従い Conventional Commits 仕様でコミット。
   • 例: feat(deps): upgrade flutter to 3.47 and apply migrate_design_widgets
2. PR 本文の更新:
   • 以下のテンプレートに基づき、env -u GITHUB_TOKEN -u GH_TOKEN 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**: 非表示タブのフォーカス外れ挙動の確認