This document describes the process, policy, and instructions for bumping the minimum Dart SDK version constraint across the flutter/flutter repository.
For instructions on rolling the actual Dart SDK binary/compilers into the Flutter Engine, see Rolling the Dart SDK.
Every Dart package in the flutter/flutter repository (including the flutter framework, flutter_tools, dev tools, tests, and examples) specifies a minimum Dart SDK version constraint in its pubspec.yaml:
environment: sdk: ^3.11.0-0
-0 Pre-release SuffixIt is important to include the -0 pre-release suffix (e.g., ^3.13.0-0 instead of ^3.11.0).
^3.11.0) exclude pre-release versions of that major/minor release (e.g. 3.11.0-dev or 3.11.0-5.0.pre).master branch tracks Dart's active development and beta branches, developers and CI run on pre-release Dart SDKs. Omitting the -0 suffix will cause package resolution to fail on pre-releases.The Dart SDK constraint bump process in the flutter/flutter repository is typically owned by team-framework. Bumps are usually performed quarterly, shortly after a new Dart stable version is released.
The Dart SDK version constraint in flutter/flutter must not exceed the current Dart stable release version. Even though the master/main branch runs on newer pre-release Dart SDKs downloaded from the Engine stamp, the minimum sdk constraint declared in our pubspec.yaml files is restricted to the stable release version.
This policy is strictly enforced for two primary reasons:
main/master branch into the active stable (or beta) release branches. If the code on main/master is allowed to use language features or dependencies requiring a newer Dart version than the stable SDK, cherry-picking those commits directly onto the stable branch becomes complicated.dart format). These updates sometimes require repo-wide refactoring or massive formatting migrations. Attempting to absorb and resolve these changes on a continuously rolling basis with unstable Dart versions is highly disruptive. Bumping quarterly to a defined stable target allows the team to manage and absorb formatting/lint sweeps predictably.[!IMPORTANT] Before planning or executing a constraint bump, the target Dart SDK version must already have rolled into the
flutter/flutterrepository via an Engine roll. If the SDK constraint in the pubspecs is bumped to a version newer than the SDK downloaded in the local cache, CI, tests, and static analysis will fail.
When a Dart SDK bump introduces new language features, they should not be adopted ad-hoc across the codebase. Instead:
Because the repository contains over 100 pubspec.yaml files (including packages, tools, manual/integration tests, and examples), the change must be made systematically.
pubspec.yaml FilesUpdate the SDK constraint in all pubspec.yaml files across the repository. You can use a search-and-replace command or a script to automate this:
# Example using find and sed to bump from ^3.10.0-0 to ^3.13.0-0 find . -name "pubspec.yaml" -not -path "*/.dart_tool/*" -exec sed -i '' 's/sdk: \^3.10.0-0/sdk: \^3.13.0-0/g' {} +
Flutter enforces a dependency checksum at the bottom of each pubspec.yaml. Run the update-packages tool to re-solve the package workspace, generate updated pubspec.lock files, and update the checksums:
flutter update-packages --force-upgrade --update-hashes
Run the repo-wide analysis script to verify the new constraints solve correctly and do not introduce any analyzer errors or lints:
dart --enable-asserts dev/bots/analyze.dart
Follow this by running the test suites on your target platforms to ensure no runtime regressions occur, e.g.:
flutter test packages/flutter_tools flutter test packages/flutter
Commit the updated pubspec.yaml, pubspec.lock files, and checksum updates, then submit a pull request.
[!WARNING] If your PR breaks Google internal (Google3) integration due to unresolved Dart SDK version mismatches, it may be reverted. Coordinate with the current Flutter roll managers to ensure alignment.