Skip to content

Commit 66aaa9a

Browse files
authored
Add docs on bumping Dart (flutter#187540)
Adds documentation on how we should update the Dart SDK in flutter/flutter. I have also wrapped this process up in a skill, but in following the instructions for adding skills to the repo, I want to test it out first. I'll be bumping Dart next to take it for a test drive. 😎 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [ ] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 4578896 commit 66aaa9a

2 files changed

Lines changed: 92 additions & 1 deletion

File tree

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Bumping the Dart SDK Version Constraint
2+
3+
This document describes the process, policy, and instructions for bumping the minimum Dart SDK version constraint across the `flutter/flutter` repository.
4+
5+
For instructions on rolling the actual Dart SDK binary/compilers into the Flutter Engine, see [Rolling the Dart SDK](Rolling-Dart.md).
6+
7+
---
8+
9+
## Overview
10+
11+
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`:
12+
13+
```yaml
14+
environment:
15+
sdk: ^3.11.0-0
16+
```
17+
18+
### The `-0` Pre-release Suffix
19+
It is important to include the `-0` pre-release suffix (e.g., `^3.13.0-0` instead of `^3.11.0`).
20+
* **Why:** According to Dart package resolution rules, standard caret constraints (like `^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`).
21+
* Since Flutter’s `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.
22+
23+
---
24+
25+
## Policy and Cadence
26+
27+
### Ownership and Cadence
28+
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.
29+
30+
### The Stable Version Constraint Policy
31+
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.
32+
33+
This policy is strictly enforced for two primary reasons:
34+
35+
1. **Stable Branch Cherry-picks:**
36+
Flutter frequently needs to cherry-pick bug fixes from the `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.
37+
2. **Formatting, Lints, and Migrations:**
38+
Upgrading the minimum Dart version often triggers new static analysis lints, deprecation warnings, or changes in code formatting (`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.
39+
40+
> [!IMPORTANT]
41+
> Before planning or executing a constraint bump, the target Dart SDK version must already have rolled into the `flutter/flutter` repository 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.
42+
43+
### New Language Features and Style Guide Updates
44+
45+
When a Dart SDK bump introduces new language features, they should not be adopted ad-hoc across the codebase. Instead:
46+
1. **Style Guide Updates:** The new features should be evaluated and documented in the [Style guide for Flutter repo](../contributing/Style-guide-for-Flutter-repo.md) to define standard patterns and decide if any usage should be restricted or preferred.
47+
2. **Organized Migration:** To maintain consistency and avoid fragmented code styles, migrations to adopt new features are usually organized as a coordinated effort. This typically involves opening a tracking issue (such as [issue #172188](https://github.com/flutter/flutter/issues/172188)) to manage and review the migration systematically.
48+
49+
---
50+
51+
## How to Bump the Dart SDK Constraint
52+
53+
Because the repository contains over 100 `pubspec.yaml` files (including packages, tools, manual/integration tests, and examples), the change must be made systematically.
54+
55+
### Step 1: Update `pubspec.yaml` Files
56+
Update 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:
57+
58+
```bash
59+
# Example using find and sed to bump from ^3.10.0-0 to ^3.13.0-0
60+
find . -name "pubspec.yaml" -not -path "*/.dart_tool/*" -exec sed -i '' 's/sdk: \^3.10.0-0/sdk: \^3.13.0-0/g' {} +
61+
```
62+
63+
### Step 2: Force Upgrade & Update Hashes
64+
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:
65+
66+
```bash
67+
flutter update-packages --force-upgrade --update-hashes
68+
```
69+
70+
### Step 3: Run Static Analysis & Tests
71+
Run the repo-wide analysis script to verify the new constraints solve correctly and do not introduce any analyzer errors or lints:
72+
73+
```bash
74+
dart --enable-asserts dev/bots/analyze.dart
75+
```
76+
77+
Follow this by running the test suites on your target platforms to ensure no runtime regressions occur, e.g.:
78+
79+
```bash
80+
flutter test packages/flutter_tools
81+
flutter test packages/flutter
82+
```
83+
84+
### Step 4: Open a Pull Request
85+
Commit the updated `pubspec.yaml`, `pubspec.lock` files, and checksum updates, then submit a pull request.
86+
87+
> [!WARNING]
88+
> 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.

‎docs/infra/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ This is an index of team-facing documentation for topics relating to Engineering
44

55
- [Autorollers](Autorollers.md)
66
- [Autosubmit bot](Autosubmit-bot.md)
7+
- [Bumping the Dart SDK version](Bumping-the-Dart-SDK-version.md)
78
- [Dashboards](Dashboards.md)
89
- [Experimental Branch](Experimental-Branch.md)
910
- [Flutter FirebaseLab Tests](Flutter-FirebaseLab-Tests.md)
@@ -15,4 +16,6 @@ This is an index of team-facing documentation for topics relating to Engineering
1516
- [Flutter's repository architecture](../about/Flutter's-repository-architecture.md)
1617
- [GitHub Action Workflows](GitHub-Action-Workflows.md)
1718
- [Labeling PRs](../contributing/Labeling-PRs.md)
18-
- [New Android Version](../platforms/android/New-Android-version.md)
19+
- [New Android Version](../platforms/android/New-Android-version.md)
20+
- [Rolling the Dart SDK](Rolling-Dart.md)
21+
- [Updating dependencies in Flutter](Updating-dependencies-in-Flutter.md)

0 commit comments

Comments
 (0)