dart-sdk-changelog
Skill35 starsChanged 3 months agoMITView on GitHub
Authoritative guide for Dart SDK language specifications, syntax availability, minimum SDK constraints (minSdk), and version changelogs from Dart 1.x through Dart 3.x. Use this skill whenever authoring or refactoring Dart code, inspecting pubspec.yaml sdk constraints, writing control flow (switch statements, pattern matching, switch expressions), implementing class constructors (primary constructors, parameter shorthands), using macros/augmentations, verifying language feature availability against the project's minSdk, or modernizing legacy codebases.
In this repository2 other files it gives its agents.
- AGENTS.mdAGENTS.md
- flutter-sdk-changelogSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 21
When writing or reviewing Dart code, selecting the correct minimum SDK lower bound (minSdk) in pubspec.yaml is essential to ensure syntax …
- Very specific: line 113
Use augment class, augment void method(), and call augmented() to wrap original logic.
- Distinctive: line 116
Check if the feature has already graduated to stable in the active SDK before adding a flag.
- Very specific: line 117
If experimental, configure analysis_options.yaml under analyzer.enable-experiment: [name].
- Distinctive: line 119
Ensure experimental code is isolated so production packages remain publishable on pub.dev.
- Very specific: line 122
Check current language version from pubspec.yaml environment block.
- Distinctive: line 123
If pre-2.12, read the Legacy Rescue Guide.
- Very specific: line 128
Read the corresponding reference document under references/.
- Distinctive: line 136
Check the Language Feature Matrix and How to Find minSdk Guide.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Dart SDK Changelog & Version Feature Guide (Dart 1.x to Modern Dart 3.x)
This skill provides an authoritative, structured guide to Dart language features, core library APIs, tooling changes, version requirements, experimental feature flags (--enable-experiment), static metaprogramming (Macros & Augmentations), and legacy modernization runbooks sourced directly from the official Dart SDK CHANGELOG.
🎯 Parent Guide: How to Find the minSdk for Any Dart Feature or API
When writing or reviewing Dart code, selecting the correct minimum SDK lower bound (minSdk) in pubspec.yaml is essential to ensure syntax and core APIs compile across target environments.
1. Language Version vs. SDK Version
- Language Version (
major.minor): Inpubspec.yaml, the lower bound ofenvironment.sdk(for example^3.13.0or>=3.12.0 <4.0.0) dictates which language grammar and compiler semantics are enabled.- Patch numbers (
.1,.2) do not affect language grammar. - Using a Dart 3.13 feature (like Primary Constructors) requires
sdk: '^3.13.0'.
- Patch numbers (
- Core Library APIs: Methods and classes (for example
Future.pause,List.unmodifiableOf) are added in specific SDK versions. - Per-file override: A file can specify
// @dart = 3.12on line 1 to force an earlier language version.
2. Fast minSdk Language Feature Matrix
| Feature / Syntax | Minimum SDK | Example Syntax | Reference |
this Type Promotion & Join-Point Promotion | 3.15.0 (beta) | if (this is Circle) print(radius); | 3.15 Guide |
| Primary Constructors | 3.13.0 | class Point(var int x, var int y); / this : assert(...) | 3.13 Guide |
| Constructor Keyword Shorthands | 3.13.0 | new(this.x); / factory clone(...) => ...; | 3.13 Guide |
| Private Named Parameters | 3.12.0 | Point({required this._x, required this._y}); | 3.12 Guide |
Wildcard Variables (_) | 3.7.0 | var (_, b) = pair; / void fn(int _, int _) | 3.7 Guide |
| Type Inference Using Bounds | 3.7.0 | Inferred types respect type parameter bounds | 3.7 Guide |
| Digit Separators | 3.6.0 | 1_000_000, 0x4000_0000, 0.000_001 | 3.6 Guide |
| Extension Types | 3.3.0 | extension type Meters(int value) {} | 3.0-3.5 Guide |
| Private Field Promotion | 3.2.0 | if (_privateFinalField != null) { ... } | 3.0-3.5 Guide |
| Records (Tuples) | 3.0.0 | (int, String) pair = (1, 'a'); | 3.0-3.5 Guide |
| Pattern Matching & Destructuring | 3.0.0 | var (a, b) = pair; / switch (val) { case ... } | 3.0-3.5 Guide |
| Switch Expressions | 3.0.0 | var s = switch (e) { 0 => 'a', _ => 'b' }; | 3.0-3.5 Guide |
| If-Case Statements & Elements | 3.0.0 | if (json case {'id': int id}) ... | 3.0-3.5 Guide |
| Sealed Classes & Exhaustiveness | 3.0.0 | sealed class State {} | 3.0-3.5 Guide |
Class Modifiers (base, interface, final) | 3.0.0 | interface class Api {} / final class Token {} | 3.0-3.5 Guide |
| 100% Sound Null Safety Enforced | 3.0.0 | Non-null-safe mode disallowed | 3.0-3.5 Guide |
| Super-Initializer Parameters | 2.17.0 | SubClass(super.name, {super.key}); | Dart 2 Milestones |
| Enhanced Enums | 2.17.0 | enum Status { ok(200); final int c; const Status(this.c); } | Dart 2 Milestones |
| Named Arguments Anywhere | 2.17.0 | fn(1, named: 'a', 2); | Dart 2 Milestones |
| Constructor Tear-Offs | 2.15.0 | List.filled, Point.new | Dart 2 Milestones |
Triple-Shift Operator (>>>) | 2.14.0 | int result = a >>> b; | Dart 2 Milestones |
Generic Type Aliases (typedef) | 2.13.0 | typedef JsonMap = Map<String, dynamic>; | Dart 2 Milestones |
Sound Null Safety (?, late, !) | 2.12.0 | Sound static non-nullable types | Dart 2 Milestones |
| Extension Methods | 2.7.0 | extension on String { ... } | Dart 2 Milestones |
Spread Operators (..., ...?) | 2.3.0 | [...list1, ...?maybeList] | Dart 2 Milestones |
Collection if and for | 2.3.0 | [if (cond) a, for (var x in l) x * 2] | Dart 2 Milestones |
Sound Type System & Optional new | 2.0.0 | Static sound types replace dynamic checks | Dart 2 Milestones |
👉 For deep-dive and verification procedures, see How to Find minSdk and the Full Version Matrix.
⚡ Subskill Spotlights
Subskill: Augmentations & Static Metaprogramming (Macros)
- Augmentation Syntax: Declare
augment class,import augment, and wrap methods usingaugmented(). - Macro Phases: Understand Type, Declaration, and Definition macro execution in the analysis server.
- In-Memory Code Gen: Eliminate
build_runnerwith zero-disk.g.dartpollution. 👉 Read the full Macros & Augmentations Guide.
Subskill: Experimental Features & Compiler Flags (--enable-experiment)
- Enabling Experiments: Configure
analysis_options.yaml(analyzer.enable-experiment), CLI flags (dart --enable-experiment=...), and VS Code settings. - Release Pipeline: Understand the graduation path across Beta preview, Stable-gated, and Stable-ungated tiers. 👉 Read the full Experimental Features Guide.
Subskill: Rescuing Legacy Codebases (Dart 1.x & Pre-2.12 to Modern Dart)
- Sound Null Safety Migration: Transform
@requiredannotations, uninitialized nullable fields, and defensive runtime assertions. - Dependency Upgrades: Modernize
pubspec.yamlenvironment bounds and replace deprecated legacy packages (pedantic,tuple, etc.). 👉 Read the full Legacy Codebase Rescue Guide.
📚 Table of Contents (TOC) & Version Archive
| Release / Guide | Focus Area | Key Additions | Reference Document |
| Macros & Augmentations | Metaprogramming | augment, augmented(), import augment, @JsonCodable(), 3-phase macro pipeline | Macros & Augmentations Guide |
| Experimental Features | Compiler Flags | --enable-experiment, Beta preview vs stable-gated release tiers, graduation matrix | Experiments Guide |
| Legacy Rescue | Migration Runbook | Dart 1.x/2.x to Modern 3.x modernization pipeline, null-safety bridge, package replacements | Rescue Guide |
| Dart 3.15 (Beta) | Flow Analysis & Math | this type promotion, join-point promotion, single show/hide combinator restriction, double.maxSafeInteger, imul32, Int32x4.operator * | 3.15 Reference |
| Dart 3.14 | CLI, SIMD & JS Interop | dart migrate, dart run -e, NativeFinalizer.callback, rangeEquals, fast JS array & async Function.toJS conversions | 3.14 Reference |
| Dart 3.13 | Language & Runtime | Primary constructors, this constructor body, new/factory shorthands, Future.pause, List.unmodifiableOf | 3.13 Reference |
| Dart 3.12 | Language & Tooling | Private named parameters (Point({this._x})), RegExp spans, dart run <pkg>@<ver> | 3.12 Reference |
| Dart 3.11 | Platform & Pub | Windows Unix domain sockets, Workspace globs (pkgs/*), dart pub cache gc | 3.11 Reference |
| Dart 3.10 | Extensibility & CLI | Analyzer plugins stable, Hooks (native assets) stable, dart install, @Deprecated constructors | 3.10 Reference |
| Dart 3.9 | Analysis & Pub | AOT analysis server, git tag version solving, null-safety assumptions in flow analysis | 3.9 Reference |
| Dart 3.8 | Formatter & Docs | Doc imports (@docImport), tall formatter trailing comma preservation, Iterable.withIterator | 3.8 Reference |
| Dart 3.7 | Language & Formatter | Wildcard variables (_), inference using bounds, tall style formatter default, legacy web deprecations | 3.7 Reference |
| Dart 3.6 | Language & Pub | Digit separators (1_000_000), Pub workspaces, dart pub bump | 3.6 Reference |
| Dart 3.0 – 3.5 | Foundation & Major Features | Records, Patterns, Switch Expressions, Sealed Classes, Class Modifiers, Extension Types, Field Promotion, Wasm | 3.0–3.5 Reference |
| Dart 2.0 – 2.19 | Historical Milestones | Sound Null Safety (2.12), Enhanced Enums & Super-Params (2.17), Extension Methods (2.7), Spreads (2.3), Sound Type System (2.0) | Dart 2 Milestones |
🛠️ Recommended Runbooks
1. Working with Augmentations & Macros
- Review Macros & Augmentations Guide.
- Wire original files with
import augment 'foo.g.dart';and augmentation files withaugment library 'foo.dart';. - Use
augment class,augment void method(), and callaugmented()to wrap original logic.
2. Working with Experimental Feature Flags
- Check if the feature has already graduated to stable in the active SDK before adding a flag.
- If experimental, configure
analysis_options.yamlunderanalyzer.enable-experiment: [name]. - Pass
--enable-experiment=nametodart run,dart test,flutter run, andflutter test. - Ensure experimental code is isolated so production packages remain publishable on pub.dev.
3. Modernizing / Rescuing a Legacy Codebase
- Check current language version from
pubspec.yamlenvironment block. - If pre-2.12, read the Legacy Rescue Guide.
- Execute the 4-stage pipeline: syntax cleanup → sound null safety → dependency bump (
sdk: ^3.5.0or^3.13.0) → Dart 3 modernization.
4. Answering "What's New in Dart X.Y"
- Identify the requested version.
- Read the corresponding reference document under
references/. - Provide:
- Language syntax changes with before/after code snippets.
- Core library additions (
dart:core,dart:async,dart:io,dart:js_interop,dart:isolate,dart:ffi). - Tooling and CLI features (
dart analyze,dart format,dart pub,dart build). - Breaking changes and migration instructions.
5. Answering "How to find minSdk for X"
- Check the Language Feature Matrix and How to Find minSdk Guide.
- Specify the exact lower bound SDK constraint for
pubspec.yaml(for examplesdk: '^3.13.0'). - Explain if the feature is a language grammar feature (requiring language version update) or a core library API.
- Show how to verify using
dart analyze.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

