Dart Flutter SDK Upgrade

VGV Flutter/Dart SDK Upgrade — Quick Reference

One PR per project. Only CI workflow and pubspec.yaml changes — no logic, no dependency version bumps, no test changes.

Core Standards

Apply these standards to all SDK upgrade work:

• Flutter and Dart versions differ — a Flutter release ships a Dart SDK whose version number is unrelated to it, and the pubspec sdk: constraint takes the Dart number, never the Flutter one. Look the pairing up in the release archive at https://docs.flutter.dev/install/archive
• Never state a bundled Dart version from memory — not from recall, not by inference from the Flutter number, and not from an example in this file. Either the user supplied the Dart version, or you read it off the archive, or you ask. There is no fourth source
• Flutter CI uses MAJOR.MINOR.x — no caret, .x wildcard resolves to latest patch
• Dart CI uses exact patch — MAJOR.MINOR.PATCH, no caret, no wildcard
• pubspec pins exact patch — use ^MAJOR.MINOR.PATCH with the specific patch version
• Pure Dart packages — use the Dart version directly, no Flutter mapping needed. The CI key is dart_sdk in dart_package.yml, not flutter_version in flutter_package.yml, and the environment block gets sdk: with no flutter: line beside it
• Write the CI block even without the file — the reusable workflow and its version key are determined by the package type, so a workflow you have not seen is still a known shape. Produce the with: block from the CI workflows section below and name the file it belongs in rather than asking for the file first
• Verify with pub get and analyze — don't silently resolve conflicts
• Decline out-of-scope edits, don't caveat them — when asked to also bump a dependency, fix a lint, or change code, do not produce that edit at all. Deliver the SDK constraint and CI changes, report the rest as separate follow-up work

0. Resolve target version

Flutter bundles a specific Dart release, and the two version numbers are unrelated. A bump to Flutter 3.35.5 does not make the Dart constraint ^3.35.5, and the Dart number cannot be derived from the Flutter number by any rule. Every SDK upgrade therefore starts with two versions, not one: the Flutter release being targeted, and the Dart release it ships.

How to find the Dart version:

1. Open https://docs.flutter.dev/install/archive
2. Find the target Flutter stable release
3. Note the Dart version listed alongside it

The Flutter target comes from $ARGUMENTS when the user supplied one. If $ARGUMENTS is empty or still shows the literal text $ARGUMENTS (the host did not substitute it), take the latest Flutter stable from that same page. For pure Dart packages, no mapping is involved: the Dart version is whatever $ARGUMENTS specifies or the latest Dart stable.

When the archive is out of reach, which is the common case in a session with no network access, do not fill the gap from memory. A recalled pairing is wrong often enough to break pub get, and it is wrong silently — the constraint looks plausible in the diff. Say the Dart version has to come off the archive, name the page as the source, and ask the user to confirm it. If the user already supplied both numbers, use them as given and say which is which.

State both resolved versions and get confirmation before editing any file.

1. CI workflows — .github/workflows/

VGV packages use VeryGoodOpenSource/very_good_workflows reusable workflows. Leave the @v1 tag untouched. Flutter packages use MAJOR.MINOR.x — no caret, literal x as the patch wildcard so CI resolves to the latest patch automatically. Dart packages pin the exact patch version. When bumping versions, update MAJOR and/or MINOR as appropriate (e.g., 3.41.x → 3.42.x or 4.0.x):

Flutter package:

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 package — note the key is dart_sdk, not flutter_version. Use the Dart version, not the Flutter version:

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

If a file uses flutter_channel: stable instead of a pinned version, pin the version — VGV always pins Flutter versions in CI workflows.

When the workflow file is not in hand

A VGV package's CI is one job calling one of the two reusable workflows above, so the block that needs changing is fully determined by the package type. When the workflow lives in another checkout, or the user described it instead of pasting it, write the with: block from the shapes above rather than stalling on the file. Say which workflow and which key you are targeting — dart_package.yml with dart_sdk for a pure Dart package, flutter_package.yml with flutter_version for a Flutter one — and present it as the block to merge into the existing job.

Two things are not invented that way. Do not fabricate the surrounding name:, on: or jobs: keys when you have not seen them, and do not guess a version number. Show the with: block and name the file it belongs in.

# 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"