Make Flutter version a single source of truth for Dart SDK
- Add sdk/dart/.flutter-version as the canonical Flutter version file - Update CI to use flutter-version-file instead of hardcoded version - Tighten pubspec.yaml environment to sdk >=3.8.0 and flutter >=3.32.0 - Document the rule and rationale in SKILL.md, including dependency bump steps - Add troubleshooting for Dart SDK version solving failures in SKILL.md
Seto Elkahfi committed
Apr 8, 2026 at 23:12 UTC
7c90647482020560b77ab21721865a05d1b4d401
4 files changed
+63
-6
.agents/skills/sdk-dart/SKILL.md
+58
-2
@@ -161,6 +161,61 @@ analyzer:
161
162
---
163
164
+### 11. Flutter version is a single source of truth — never hardcode it in CI
165
+
166
+The CI workflow reads the Flutter version from `sdk/dart/.flutter-version` via
167
+`subosito/flutter-action`'s `flutter-version-file:` parameter. **Never
168
+hardcode `flutter-version: "x.y.z"` directly in the workflow YAML.**
169
+
170
+```
171
+sdk/dart/.flutter-version ← only place the Flutter version is written
172
+```
173
+
174
+```yaml
175
+# .github/workflows/release-sdk-dart.yml (both jobs)
176
+- name: Set up Flutter
177
+ uses: subosito/flutter-action@v2
178
+ with:
179
+ flutter-version-file: sdk/dart/.flutter-version # reads .flutter-version
180
+ channel: stable
181
+ cache: true
182
+```
183
+
184
+**Why this matters:** Each Flutter release ships a specific Dart SDK version.
185
+Dev dependencies like `freezed` have minimum Dart SDK requirements that advance
186
+faster than Flutter stable releases. When you bump a Flutter-sensitive dep,
187
+you must also bump the Flutter version used in CI — and `.flutter-version` is
188
+the one place to do that.
189
+
190
+**Rule: when bumping a dep that constrains the Dart SDK** (e.g. `freezed`,
191
+`flutter_rust_bridge`, `build_runner`):
192
+
193
+1. Run `flutter pub get` locally — a version-solving failure tells you
194
+ immediately if the Dart SDK shipped with the current Flutter is too old.
195
+2. Find the Flutter release that ships the required Dart SDK version
196
+ (see https://docs.flutter.dev/release/archive).
197
+3. Update `sdk/dart/.flutter-version` to that version.
198
+4. Tighten `pubspec.yaml`'s `environment.sdk` lower bound to match — it must
199
+ honestly reflect what your deps need, not what you originally wrote.
200
+
201
+**`pubspec.yaml` environment constraint must be accurate:**
202
+
203
+```yaml
204
+# WRONG — lying lower bound causes CI to pass locally but fail on old runners
205
+environment:
206
+ sdk: ">=3.3.0 <4.0.0" # freezed ^3.2.x actually requires >=3.8.0
207
+
208
+# CORRECT
209
+environment:
210
+ sdk: ">=3.8.0 <4.0.0"
211
+ flutter: ">=3.32.0"
212
+```
213
+
214
+An inaccurate `sdk:` lower bound is invisible locally (you're already on a
215
+newer SDK) but breaks any runner or user on the stated minimum.
216
+
217
+---
218
+
219
## Package Structure Reference
220
221
```
@@ -222,8 +277,8 @@ homepage: https://ondeinference.com
277
issue_tracker: https://github.com/ondeinference/onde/issues
278
279
environment:
225
- sdk: '>=3.3.0 <4.0.0'
226
- flutter: '>=3.10.0'
280
+ sdk: '>=3.8.0 <4.0.0' # must reflect the actual minimum required by deps
281
+ flutter: '>=3.32.0' # Flutter 3.32 ships Dart 3.8; update .flutter-version too
282
283
dependencies:
284
flutter:
@@ -824,6 +879,7 @@ If they drift, generated code won't compile. Always check both when upgrading.
879
| `ld: error: unknown argument '-Xlinker'` / `-dynamiclib` / `-filelist` | Android NDK's `ld` (LLD) is on PATH — Xcode picks it up instead of Apple's linker | Remove `export LD=$TOOLCHAIN/bin/ld` and other NDK tool exports from `~/.zshrc` (see Xcode 26 section) |
880
| `clang: error: invalid linker name in argument '-fuse-ld=classic'` | `ALTERNATE_LINKER = classic` set but clang doesn't support it | Remove `ALTERNATE_LINKER`; was only needed to work around the NDK-on-PATH issue — once that's fixed, Apple's ld-prime works fine |
881
| `EntityTooLarge` on `dart pub publish` | Package > 100 MB (rust/target/ included) | Create `.pubignore` excluding `rust/target/`, `**/*.a`, `**/*.so`, etc. |
882
+| `Because <pkg> requires SDK version >=X.Y.0 ... version solving failed` | `pubspec.yaml` `environment.sdk` lower bound is too old; CI Flutter version too old | 1. Update `sdk/dart/.flutter-version` to a Flutter that ships the required Dart SDK. 2. Tighten `environment.sdk` in `pubspec.yaml` to the real minimum. See Hard-Won Lesson 11. |
883
884
## Xcode 26 Compatibility
885
.github/workflows/release-sdk-dart.yml
+2
-2
@@ -25,7 +25,7 @@ jobs:
25
- name: Set up Flutter
26
uses: subosito/flutter-action@v2
27
with:
28
- flutter-version: "3.27.x"
28
+ flutter-version-file: sdk/dart/.flutter-version
29
channel: stable
30
cache: true
31
@@ -84,7 +84,7 @@ jobs:
84
- name: Set up Flutter
85
uses: subosito/flutter-action@v2
86
with:
87
- flutter-version: "3.27.x"
87
+ flutter-version-file: sdk/dart/.flutter-version
88
channel: stable
89
cache: true
90
sdk/dart/.flutter-version
new
+1
@@ -0,0 +1 @@
1
+3.32.2
sdk/dart/pubspec.yaml
+2
-2
@@ -9,8 +9,8 @@ issue_tracker: https://github.com/ondeinference/onde/issues
9
license: MIT OR Apache-2.0
10
11
environment:
12
- sdk: ">=3.3.0 <4.0.0"
13
- flutter: ">=3.10.0"
12
+ sdk: ">=3.8.0 <4.0.0"
13
+ flutter: ">=3.32.0"
14
15
dependencies:
16
flutter: