Frb Upgrade Flutter

1 Start here

• Confirm the target Flutter stable release from official Flutter sources.
• Read frb-dev-env before running setup, generation, lint, or tests. Use its per-worktree local Docker workflow.
• Read frb-upgrade-docker when the target toolchain changes the development image.
• Read frb-docker for ordinary local Docker usage.
• Read frb-code-generation before accepting generated or scaffold drift.
• Read frb-cargokit before changing any copied CargoKit file. Read frb-cargokit-dev only when the source change belongs in the external CargoKit repository.
• Read frb-pr-chain-split as soon as an independently landable prerequisite or cleanup appears.
• Read frb-prepare-pr and then frb-pr-review before treating the upgrade PR as ready.
• Read frb-fix-ci when CI starts failing.

2 Establish the version contract

• Record the target Flutter version, bundled Dart version, release date, and relevant release-note changes.
• Distinguish the primary Dart version from the minimum supported Dart SDK floor.
  • Upgrade the primary Dart pin with Flutter.
  • Do not raise package SDK constraints merely because the primary toolchain is newer.
  • When retaining an older SDK floor, run dependency resolution, analysis, and tests on that floor in CI.
• Inventory version-like values without assuming the target Dart major or minor:

rg -n "FRB_MAIN_|FLUTTER_VERSION|DART_VERSION|RUST_VERSION|setup-flutter|setup-dart|cirruslabs/flutter"
rg -n "flutter_rust_bridge_dev|stable|nightly|minimum.*version|deployment.*target" \
  .devcontainer .github tools frb_codegen frb_example

• Inspect at least:
  • .devcontainer/Dockerfile;
  • .github/workflows/ci.yaml and .github/workflows/post_release.yaml;
  • .github/workflows/publish_dev_docker.yaml;
  • tools/frb_internal/test/src/makefile_dart/test_dev_docker_metadata.dart;
  • package pubspec.yaml and checked-in pubspec.lock files;
  • frb_codegen/assets/integration_template/**;
  • tools/frb_internal/assets/apple_scaffold/**;
  • tools/tart_macos/**;
  • frb_example/**.

3 Choose PR boundaries before implementation

• When the development image changes, make its upgrade the first independent predecessor PR targeting master. Follow frb-upgrade-docker for its contents, candidate image, merge order, and stable-tag promotion.
• Keep generated snapshots, their generator changes, required tests, and upgrade-specific compatibility migrations in the main upgrade PR.
• Split independent bug fixes, hardening, and reusable prerequisites into predecessor PRs according to frb-pr-chain-split.
• Build and maintain any predecessor chain exclusively with the official gh stack workflow described there.
• Put ci-manual-dispatch on dormant predecessors unless a predecessor specifically needs GitHub-only validation.
• Do not move incidental skill or workflow cleanup into the upgrade PR when it can stand alone against master.

4 Upgrade the development toolchain

• Complete the independent Docker predecessor through frb-upgrade-docker before relying on the upgraded image.
• Use its immutable candidate tag for pre-merge validation when necessary; never move latest from a PR branch.
• After the predecessor merges and publishes stable tags, merge latest master into the remaining upgrade chain and use the canonical version tag.
• If Apple pins, simulators, or host tooling change, continue with the Tart workflow routed by frb-dev-env and read frb-tart-prepare before provisioning or validation.

5 Synchronize CI and post-release pins

• Update the top-level toolchain values together in .github/workflows/ci.yaml and .github/workflows/post_release.yaml:
  • FRB_MAIN_FLUTTER_VERSION;
  • FRB_MAIN_DART_VERSION;
  • FRB_MAIN_RUST_VERSION when the upgraded tooling requires it;
  • FRB_RUSTFMT_NIGHTLY_VERSION only when formatting or nightly rust-src behavior requires it.
• Keep a retained minimum Dart floor explicit and independently exercised; do not substitute the primary Dart pin for that compatibility lane.
• Review Java, Android SDK/NDK, Chrome/chromedriver, macOS runner, simulator, Windows ARM, and post-release install-mode assumptions.