Update guidance on bumping Dart (#193131)
Adds important context about LSC and aligning with the release process
## 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].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant in-code documentation (doc comments with
`///`).
- [x] If this PR introduces a new feature or capability, I created and
linked a website documentation issue or PR in [flutter/website] (or
verified none is needed).
- [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
[flutter/website]: https://github.com/flutter/website
[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
diff --git a/.github/workflows/quarterly-scheduled-tasks.yml b/.github/workflows/quarterly-scheduled-tasks.yml
index 1049da4..1b5439b 100644
--- a/.github/workflows/quarterly-scheduled-tasks.yml
+++ b/.github/workflows/quarterly-scheduled-tasks.yml
@@ -91,7 +91,7 @@
BODY: |
### Quarterly Dart SDK Constraint Bump
- **Context**: Ahead of the upcoming stable release, the minimum Dart SDK version constraint across `flutter/flutter` should be bumped to align with the current stable release.
+ **Context**: Ahead of the upcoming stable release, the minimum Dart SDK version constraint across `flutter/flutter` should be bumped to align with the current stable release. If and when bumping Dart in the repo requires a large scale change (LSC)—for example, to re-format the repo—the release team should be included in the process. The LSC will need to follow branch alignment so as to not disrupt the release process.
See [Bumping the Dart SDK version constraint](https://github.com/flutter/flutter/blob/main/docs/infra/Bumping-the-Dart-SDK-version.md) for full instructions and policies.
@@ -110,6 +110,7 @@
```bash
dart --enable-asserts dev/bots/analyze.dart
```
+ - [ ] **Check for Large Scale Changes (LSC)**: If the bump requires a large scale change (e.g., to re-format the repo), include the release team in the process and ensure the LSC follows branch alignment so as to not disrupt the release process.
- [ ] Open PR in `flutter/flutter` to close this issue.
*This issue was automatically generated by GitHub Actions workflow.*
diff --git a/docs/infra/Bumping-the-Dart-SDK-version.md b/docs/infra/Bumping-the-Dart-SDK-version.md
index 7bf6a46..95d2ad9 100644
--- a/docs/infra/Bumping-the-Dart-SDK-version.md
+++ b/docs/infra/Bumping-the-Dart-SDK-version.md
@@ -37,6 +37,10 @@
2. **Formatting, Lints, and Migrations:**
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.
+### Large Scale Changes (LSCs) and Release Alignment
+
+If and when bumping Dart in the repository requires a large scale change (LSC)—for example, to re-format the repository (`dart format`) or perform a repo-wide lint migration—the **release team** must be included in the process. The LSC must follow branch alignment so as not to disrupt the release process (e.g., avoiding widespread merge conflicts for cherry-picks across active release branches).
+
> [!IMPORTANT]
> 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.
diff --git a/docs/infra/Scheduled-Recurring-Tasks.md b/docs/infra/Scheduled-Recurring-Tasks.md
index 150dc39..f0f15e8 100644
--- a/docs/infra/Scheduled-Recurring-Tasks.md
+++ b/docs/infra/Scheduled-Recurring-Tasks.md
@@ -97,4 +97,4 @@
| :--- | :--- | :--- | :--- |
| **Localization Update** | [quarterly-scheduled-tasks.yml](../../.github/workflows/quarterly-scheduled-tasks.yml) | Prompts team to check for new upstream strings, pull translations from internal console, update `flutter_localizations`, Material, and Cupertino localizations, run tests, submit PR, and file follow-up issues if stable roll is required. | `automated task`, `a: internationalization`, `team-framework` |
| **Goldctl Version Update** | [quarterly-scheduled-tasks.yml](../../.github/workflows/quarterly-scheduled-tasks.yml) | Prompts team to find the latest `goldctl` git revision, update `goldctl` dependencies in `.ci.yaml` across `flutter/flutter` and `flutter/packages`, verify golden file tests, and open PRs. | `automated task`, `team-ecosystem`, `infra: flutter gold` |
-| **Dart SDK Constraint Bump** | [quarterly-scheduled-tasks.yml](../../.github/workflows/quarterly-scheduled-tasks.yml) | Prompts team to bump the minimum Dart SDK version constraint across `flutter/flutter` to align with the current stable release, update package checksums, and run static analysis and tests. | `automated task`, `team-framework` |
+| **Dart SDK Constraint Bump** | [quarterly-scheduled-tasks.yml](../../.github/workflows/quarterly-scheduled-tasks.yml) | Prompts team to bump the minimum Dart SDK version constraint across `flutter/flutter` to align with the current stable release, update package checksums, run static analysis and tests, and coordinate with the release team on branch alignment if a large scale change (LSC) is required. | `automated task`, `team-framework` |
