dart-flutter-sdk-upgrade

VGV Flutter/Dart SDK のアップグレード — クイックリファレンス

プロジェクトごとに PR は 1 つです。変更するのは CI ワークフローと pubspec.yaml のみです。ロジック、依存関係のバージョン、テストは変更しません。

---

基本基準

SDK のアップグレード作業では、以下の基準をすべて適用してください。

• Flutter と Dart のバージョンは異なります — Flutter のリリースには、そのバージョン番号とは無関係なバージョン番号の Dart SDK が含まれます。また、pubspec の sdk: 制約には Flutter のバージョンではなく、必ず Dart のバージョンを指定します。対応するバージョンは、リリースアーカイブ https://docs.flutter.dev/install/archive で確認してください
• 同梱される Dart のバージョンを記憶だけで決めないでください — 記憶や Flutter のバージョンからの推測、このファイルの例を根拠にしてはいけません。ユーザーが Dart のバージョンを指定しているか、アーカイブで確認するか、ユーザーに尋ねてください。ほかに情報源はありません
• Flutter CI では MAJOR.MINOR.x を使います — キャレットは使いません。.x のワイルドカードは最新のパッチバージョンに解決されます
• Dart CI ではパッチバージョンまで指定します — MAJOR.MINOR.PATCH を使い、キャレットもワイルドカードも使いません
• pubspec ではパッチバージョンまで固定します — 特定のパッチバージョンを使い、^MAJOR.MINOR.PATCH と指定します
• 純粋な Dart パッケージ — Flutter との対応付けは不要で、Dart のバージョンを直接指定します。CI のキーは flutter_package.yml の flutter_version ではなく、dart_package.yml の dart_sdk です。また、環境ブロックには flutter: の行を併記せず、sdk: を指定します
• ファイルがなくても CI ブロックを記述します — 再利用可能なワークフローとそのバージョンキーはパッケージの種類で決まるため、まだ確認していないワークフローでも形式は特定できます。まずファイルの提示を求めるのではなく、以下の CI ワークフローのセクションに従って with: ブロックを作成し、その記述先のファイル名を示してください
• pub get と analyze で検証します — 競合を黙って解決しないでください
• 範囲外の編集依頼には応じず、条件付きにしないでください — 依存関係のバージョン更新、lint の修正、コードの変更も求められた場合、それらの編集は一切行わないでください。SDK 制約と CI の変更を行い、残りは別途対応が必要な作業として報告してください

---

0. 対象バージョンの決定

Flutter には特定の Dart リリースが同梱されていますが、2 つのバージョン番号に関連性はありません。Flutter 3.35.5 にアップグレードしても、Dart の制約が ^3.35.5 になるわけではなく、Flutter のバージョンから Dart のバージョンを導き出すルールもありません。そのため、SDK のアップグレードでは必ず 1 つではなく、対象の Flutter リリースと、そのリリースに含まれる Dart リリースという 2 つのバージョンを最初に確認します。

Dart のバージョンの確認方法：

1. https://docs.flutter.dev/install/archive を開きます
2. 対象の Flutter 安定版リリースを探します
3. そのリリースに併記されている Dart のバージョンを確認します

ユーザーが $ARGUMENTS を指定している場合、Flutter の対象バージョンはそこから取得します。$ARGUMENTS が空、または文字列 $ARGUMENTS のままの場合（ホスト側で置換されなかった場合）は、同じページで最新の Flutter 安定版を確認してください。純粋な Dart パッケージでは対応付けは不要です。Dart のバージョンには、$ARGUMENTS に指定されたもの、または最新の Dart 安定版を使います。

アーカイブにアクセスできない場合、ネットワークに接続できないセッションではよくある状況ですが、記憶で補わないでください。記憶している対応関係は pub get を失敗させるほど間違っていることがあり、差分上ではもっともらしく見えるため、間違いに気づきにくくなります。Dart のバージョンはアーカイブで確認する必要があること、情報源となるページを伝え、ユーザーに確認を求めてください。ユーザーがすでに両方のバージョンを指定している場合は、指定どおりに使用し、どちらがどのバージョンかを明示してください。

両方のバージョンを特定し、ファイルを編集する前に確認を得てください。

1. CI ワークフロー — .github/workflows/

VGV パッケージでは、再利用可能なワークフロー VeryGoodOpenSource/very_good_workflows を使用します。@v1 タグはそのままにしてください。Flutter パッケージでは MAJOR.MINOR.x を使用します。キャレットは付けず、パッチのワイルドカードとして文字どおりの x を使うことで、CI が最新のパッチバージョンを自動的に解決します。Dart パッケージではパッチバージョンを正確に指定します。バージョンを上げる際は、必要に応じて MAJOR および／または MINOR を更新してください（例：3.41.x → 3.42.x または 4.0.x）。

Flutter パッケージ：

uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/flutter_package.yml@v1
with:
  flutter_version: "3.41.x" # ← MAJOR.MINOR.x, resolves to latest patch

Pure Dart パッケージ — キーは flutter_version ではなく dart_sdk である点に注意してください。Flutter のバージョンではなく、Dart のバージョンを使用します。

uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
with:
  dart_sdk: "3.11.0" # ← exact Dart version (not Flutter version)

ファイルで固定バージョンの代わりに flutter_channel: stable を使用している場合は、バージョンを固定してください。VGV では CI ワークフロー内の Flutter バージョンを常に固定します。

ワークフローファイルが手元にない場合

VGV パッケージの CI は、上記のいずれかの再利用可能なワークフローを呼び出す 1 つのジョブで構成されるため、変更が必要なブロックはパッケージの種類によって完全に決まります。ワークフローが別のチェックアウトにある場合や、ユーザーがファイルを貼り付けずに説明した場合は、作業を止めず、上記の形式に従って with: ブロックを記述してください。対象のワークフローとキーを明記します。Pure Dart パッケージでは dart_sdk を含む dart_package.yml、Flutter パッケージでは flutter_version を含む flutter_package.yml です。既存のジョブにマージするブロックとして提示してください。

この方法で推測してはならないものが 2 つあります。実際に確認していない name:、on:、jobs: キーを周辺の内容として捏造しないでください。また、バージョン番号を推測してはいけません。with: ブロックを示し、それが属するファイル名を明記してください。

# Pure Dart package, target Dart 3.11.0 — the block to merge into your existing job
uses: VeryGoodOpenSource/very_good_workflows/.github/workflows/dart_package.yml@v1
with:
  dart_sdk: "3.11.0"

---

2. pubspec.yaml の環境制約

形式は ^MAJOR.MINOR.PATCH です（キャレット、パッチバージョンを正確に指定）。CI とは異なり、pubspec では特定のパッチバージョンを固定します。これはユーザーが指定したバージョン、またはバージョン更新時点での最新の stable バージョンです。

Flutter パッケージ（dependencies の下に flutter: があるもの）：

environment:
  sdk: ^<dart-version> # ← the Dart version the target Flutter release ships
  flutter: ^<flutter-version> # ← the target Flutter release itself

この 2 つのプレースホルダーは意図的に残しています。値を埋めるには手順 0 でアーカイブを参照する必要があり、2 つの数値が同じになることはありません。Flutter 3.35.5 に更新する場合、flutter: 制約は ^3.35.5 で、sdk: 制約はアーカイブに 3.35.5 と併記されている Dart のバージョンになります。sdk: に Flutter のバージョンを記入することが、この変更で最もよくある間違いです。

Pure Dart パッケージ（Flutter SDK への依存がないもの）：

environment:
  sdk: ^3.11.0 # ← Dart version only
  # no flutter: line

モノレポでは、各パッケージの pubspec.yaml を個別に更新してください。共有 CI ワークフローの更新は 1 回だけで構いません。

---

3. 検証

各パッケージのディレクトリから実行します。利用可能な場合は Dart／Flutter MCP ツールを使用し、それ以外の場合は Bash を使用してください。

flutter pub get   # or: dart pub get  (for pure Dart packages)
flutter analyze   # or: dart analyze

pub get が依存関係の競合で失敗した場合は、報告してください。パッケージをアップグレードして黙って解決してはいけません。問題を引き起こしているパッケージ、そのバージョン、新しいバージョンと競合する SDK 制約を示し、判断をユーザーに委ねてください。その依存関係のバージョン引き上げは独立した PR であり、今回の PR の範囲外です。SDK の更新によって新たなエラーが analyze で検出された場合も、この PR で修正せずに報告してください。

バージョン解決の出力の読み方、競合が発生する 3 つのパターン、間接依存関係のブロッカーの追跡方法、および報告形式については、references/version-conflicts.md を参照してください。

---

4. スコープ外のリクエスト

ユーザーは、SDK の更新と追加の変更をまとめて依頼することがよくあります。「pubspec の編集ついでに、このパッケージも更新して」「新しいアナライザーの警告も修正して、CI を通るようにして」などです。追加の変更はきっぱり断ってください。禁止された編集に但し書きを添えても、拒否したことにはなりません。pubspec に新しい依存関係のバージョンを書き込み、「ここに書くべきではありません」と注記しても、変更が混在した PR がそのまま出されてしまいます。

そのため、「新しい Flutter に更新し、http の制約を引き上げて、アナライザーの警告を 2 件修正して」という依頼の場合、返す pubspec では environment ブロックのみを変更し、それ以外は変更しません。

environment:
  sdk: ^<dart-version> # ← changed, Dart version from the archive
  flutter: ^<flutter-version> # ← changed, the target Flutter release

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0 # ← left alone, dependency bumps are a separate PR

続いて、行わなかったことと、それぞれの変更をどこで行うべきかを明確に伝えてください。

• 依存関係の更新は独立した PR で行います。何かが壊れたとき、変更が混在した差分では二分探索できません。
• アナライザーの警告は修正せず、報告します。ファイル、行、ルールを列挙し、この変更の範囲外で対応できるようにしてください。

後続の対応は別の PR として提案してください。この PR にまとめることは提案しないでください。

---

5. PR のスコープ確認

コミットする前に、差分に次のファイルのみが含まれていることを確認してください。

• .github/workflows/*.yml
• pubspec.yaml（1 件以上）

git diff HEAD --name-only

コミット／PR メッセージの例：

chore: bump Flutter to <flutter-version> / Dart to <dart-version>

- Update flutter_version in .github/workflows/ to MAJOR.MINOR.x (CI resolves latest patch)
- Update dart_sdk in .github/workflows/ to the exact Dart patch
- Update environment sdk/flutter constraints in pubspec.yaml

No logic or code changes.

変更履歴を確認するレビュアーが、どの Dart リリースに伴う更新なのかを把握できるよう、件名には両方の番号を記載します。