Flutter SDK Version, Deprecation & Migration Reference

Freshness contract — read first. Generated 2026-10-30. Stable at generation time: Flutter 3.47.9 (2026-10-29) bundling Dart 3.13.7. (Cross-channel note: the Dart gap has been zero since 3.47.8 (2026-10-23) — 3.47.7 of 2026-10-08 still bundled Dart 3.13.5; the standalone Dart stable channel is 3.13.7 too, so Flutter and standalone Dart ship the same Dart patch, and the 3.47.9 patch release kept it.) Regenerate with python3 scripts/build_flutter_sdk_changelog.py --fetch (~4s; resolves the SDK from $FLUTTER_ROOT or which flutter, no hard-coded paths). Drift is detected by python3 scripts/check_freshness.py. Default mode reports and stays exit-0 — a fresh run ends with a final {"wakeAgent": false} line so a cron wake gate skips the agent, while DRIFT DETECTED output (no such line) wakes it. Use --strict for gate semantics — exit 1 on drift or unverifiable network. If the gate reports drift, regenerate before answering any version question. A non-zero exit without --strict means the script itself crashed. The gate itself is tamper-tested: python3 scripts/test_gate_tamper.py seeds five defects (stale header, deleted minor row, wrong Dart floor, wrong first-stable row, emptied deprecation reference) and requires exit 1 under --strict with the right reason for each, plus green control runs — including the wake-line convention (present when fresh, absent on drift). Network gotcha (fixed 2026-10-24 in all three scripts): this machine's Python 3.13 framework build has ssl.get_default_verify_paths().cafile is None, so urllib fetches failed with CERTIFICATE_VERIFY_FAILED while curl (which reads /etc/ssl/cert.pem) worked. Every script now builds its TLS context from certifi with a system-bundle fallback — verification is never disabled. If you see that error again, an unpatched urllib call is the cause, not an outage, and it is never a reason to regenerate.

Rule 0 — never state a Flutter version from memory

Flutter ships a new stable minor roughly every 3 months, so any version fact held in model weights is stale by construction. This skill exists because that staleness silently breaks pubspec.yaml bounds and CI.

1. Version/Dart mapping → read references/flutter-to-dart-version-matrix.md (generated).
2. Deprecated symbol → read references/widget-deprecations-and-replacements.md (generated, 217 members, Flutter 3.13 → 3.44).
3. If the answer is not in either file, verify live before answering:

   curl -s https://storage.googleapis.com/flutter_infra_release/releases/releases_macos.json | python3 -c "import json,sys; d=json.load(sys.stdin); h=d['current_release']['stable']; r=[x for x in d['releases'] if x['hash']==h][0]; print(r['version'], r['release_date'][:10], r['dart_sdk_version'])"
   flutter --version              # what THIS machine has

🎯 Highest-impact deprecations (verified against the 3.47 stable tree)

These are the ones that actually hit an app being upgraded. Full list in the generated reference.

Removed, not deprecated — hard build breaks

FlatButton → TextButton; RaisedButton → ElevatedButton; OutlineButton → OutlinedButton; TextTheme.headline1…6 / bodyText1/2 / subtitle1/2 → displayLarge…bodyLarge/titleMedium; ThemeData.accentColor → ColorScheme.secondary; Scaffold.of(context).showSnackBar → ScaffoldMessenger.of(context).showSnackBar; ThemeData.toggleableActiveColor → per-widget WidgetStateProperty. Verified absent from the 3.47 tree — these produce compile errors, not warnings.

🔗 Dart feature → required Flutter floor

A Dart language feature needs the Flutter release that bundles that Dart SDK. Derived from the generated matrix:

Pair this skill with dart-sdk-changelog for the Dart-side feature matrix.

🛠️ Runbooks

1. "What replaced X?" / analyzer reports a deprecation

1. Grep the generated reference: grep -i "<symbol>" references/widget-deprecations-and-replacements.md.
2. Try the automated migration first — Flutter policy requires a data-driven fix with every framework deprecation (docs/contributing/Tree-hygiene.md), so this usually does the whole job:

   dart fix --dry-run     # inspect
   dart fix --apply       # migrate

3. Only hand-edit what dart fix leaves behind, then flutter analyze.

2. Choosing environment: bounds for a package

1. Decide the newest Dart language feature the code actually uses (see dart-sdk-changelog).
2. Set sdk: '^<that Dart minor>'.
3. Add the matching flutter: floor from the matrix — never guess it:

   environment:
     sdk: ^3.12.0
     flutter: ">=3.44.0"

4. Verify on the machine that will build: flutter --version and dart analyze.

3. "What's new in Flutter X.Y?"

1. Confirm X.Y is a real stable minor in the matrix (Flutter skips numbers: there is no stable 3.30, 3.33, 3.36, 3.40, 3.43 — those are dev/beta cycles only).
2. State the bundled Dart SDK and release date from the matrix.
3. List the deprecations whose First stable equals X.Y from the generated reference.
4. For anything beyond that, read the official release notes rather than guessing: https://docs.flutter.dev/release/release-notes.

4. Rescuing a legacy Flutter app

1. Read the current bounds from pubspec.yaml and the matrix row for that Flutter minor.
2. Step in stable minors, never in one jump — build and run tests at each stop.
3. At each stop: dart fix --apply, then flutter analyze, then run the app.
4. Pre-3.0 (Dart < 2.12) apps must cross sound null safety first — that is a Dart-side migration; use dart-sdk-changelog's legacy rescue guide before touching widgets.
5. Material 3 is the default theme since Flutter 3.16; if the app pins useMaterial3: false, treat the M3 switch as its own change with visual review, not a side effect of the upgrade.

5. Refreshing this skill (do this, do not patch numbers by hand)

cd <this skill directory>
python3 scripts/build_flutter_sdk_changelog.py --fetch   # re-extracts the stable tree itself
python3 scripts/check_freshness.py --strict                 # must print ALL FRESH, exit 0

The generator finds the Flutter SDK via $FLUTTER_ROOT, else which flutter, and needs it to be a git checkout (standard git clone, Homebrew and fvm installs are). Pass --flutter-root PATH otherwise. Then update the "Freshness contract" block and the highest-impact table if new buckets appeared — the gate fails if that table disagrees with the generated data, so it cannot silently rot.

Automate it: attach scripts/check_freshness.py to a cron job as a wake gate (the job's script field) — fresh runs end with {"wakeAgent": false} (agent skipped silently), drift output wakes the agent with the report. In --strict mode it exits 1 on drift or unverifiable network — use that in CI. Never wire a bare non-zero-exit gate as a Hermes monitor source: the scheduler reads ANY non-zero exit as "source failed" (operator alert, no agent wake), so drift would never auto-fix.

📌 Provenance and why this is not an upstream copy

Built after auditing RandalSchwartz/dart-sdk-skills (MIT) on 2026-08-29. Its Dart half was adopted (see dart/dart-sdk-changelog); its Flutter half was rejected and rebuilt here because it carried three defects that this design structurally prevents: