agentleFS
RandalSchwartzRandalSchwartz/dart-sdk-skills/skills/dart-sdk-changelog/SKILL.md

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.

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
  1. Very specific:

    When writing or reviewing Dart code, selecting the correct minimum SDK lower bound (minSdk) in pubspec.yaml is essential to ensure syntax …

    line 21
  2. Very specific:

    Use augment class, augment void method(), and call augmented() to wrap original logic.

    line 113
  3. Distinctive:

    Check if the feature has already graduated to stable in the active SDK before adding a flag.

    line 116
  4. Very specific:

    If experimental, configure analysis_options.yaml under analyzer.enable-experiment: [name].

    line 117
  5. Distinctive:

    Ensure experimental code is isolated so production packages remain publishable on pub.dev.

    line 119
  6. Very specific:

    Check current language version from pubspec.yaml environment block.

    line 122
  7. Distinctive:

    If pre-2.12, read the Legacy Rescue Guide.

    line 123
  8. Very specific:

    Read the corresponding reference document under references/.

    line 128
  9. Distinctive:

    Check the Language Feature Matrix and How to Find minSdk Guide.

    line 136

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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): In pubspec.yaml, the lower bound of environment.sdk (for example ^3.13.0 or >=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'.
  • 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.12 on line 1 to force an earlier language version.

2. Fast minSdk Language Feature Matrix

Feature / SyntaxMinimum SDKExample SyntaxReference
this Type Promotion & Join-Point Promotion3.15.0 (beta)if (this is Circle) print(radius);3.15 Guide
Primary Constructors3.13.0class Point(var int x, var int y); / this : assert(...)3.13 Guide
Constructor Keyword Shorthands3.13.0new(this.x); / factory clone(...) => ...;3.13 Guide
Private Named Parameters3.12.0Point({required this._x, required this._y});3.12 Guide
Wildcard Variables (_)3.7.0var (_, b) = pair; / void fn(int _, int _)3.7 Guide
Type Inference Using Bounds3.7.0Inferred types respect type parameter bounds3.7 Guide
Digit Separators3.6.01_000_000, 0x4000_0000, 0.000_0013.6 Guide
Extension Types3.3.0extension type Meters(int value) {}3.0-3.5 Guide
Private Field Promotion3.2.0if (_privateFinalField != null) { ... }3.0-3.5 Guide
Records (Tuples)3.0.0(int, String) pair = (1, 'a');3.0-3.5 Guide
Pattern Matching & Destructuring3.0.0var (a, b) = pair; / switch (val) { case ... }3.0-3.5 Guide
Switch Expressions3.0.0var s = switch (e) { 0 => 'a', _ => 'b' };3.0-3.5 Guide
If-Case Statements & Elements3.0.0if (json case {'id': int id}) ...3.0-3.5 Guide
Sealed Classes & Exhaustiveness3.0.0sealed class State {}3.0-3.5 Guide
Class Modifiers (base, interface, final)3.0.0interface class Api {} / final class Token {}3.0-3.5 Guide
100% Sound Null Safety Enforced3.0.0Non-null-safe mode disallowed3.0-3.5 Guide
Super-Initializer Parameters2.17.0SubClass(super.name, {super.key});Dart 2 Milestones
Enhanced Enums2.17.0enum Status { ok(200); final int c; const Status(this.c); }Dart 2 Milestones
Named Arguments Anywhere2.17.0fn(1, named: 'a', 2);Dart 2 Milestones
Constructor Tear-Offs2.15.0List.filled, Point.newDart 2 Milestones
Triple-Shift Operator (>>>)2.14.0int result = a >>> b;Dart 2 Milestones
Generic Type Aliases (typedef)2.13.0typedef JsonMap = Map<String, dynamic>;Dart 2 Milestones
Sound Null Safety (?, late, !)2.12.0Sound static non-nullable typesDart 2 Milestones
Extension Methods2.7.0extension on String { ... }Dart 2 Milestones
Spread Operators (..., ...?)2.3.0[...list1, ...?maybeList]Dart 2 Milestones
Collection if and for2.3.0[if (cond) a, for (var x in l) x * 2]Dart 2 Milestones
Sound Type System & Optional new2.0.0Static sound types replace dynamic checksDart 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 using augmented().
  • Macro Phases: Understand Type, Declaration, and Definition macro execution in the analysis server.
  • In-Memory Code Gen: Eliminate build_runner with zero-disk .g.dart pollution. 👉 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 @required annotations, uninitialized nullable fields, and defensive runtime assertions.
  • Dependency Upgrades: Modernize pubspec.yaml environment bounds and replace deprecated legacy packages (pedantic, tuple, etc.). 👉 Read the full Legacy Codebase Rescue Guide.

📚 Table of Contents (TOC) & Version Archive

Release / GuideFocus AreaKey AdditionsReference Document
Macros & AugmentationsMetaprogrammingaugment, augmented(), import augment, @JsonCodable(), 3-phase macro pipelineMacros & Augmentations Guide
Experimental FeaturesCompiler Flags--enable-experiment, Beta preview vs stable-gated release tiers, graduation matrixExperiments Guide
Legacy RescueMigration RunbookDart 1.x/2.x to Modern 3.x modernization pipeline, null-safety bridge, package replacementsRescue Guide
Dart 3.15 (Beta)Flow Analysis & Maththis type promotion, join-point promotion, single show/hide combinator restriction, double.maxSafeInteger, imul32, Int32x4.operator *3.15 Reference
Dart 3.14CLI, SIMD & JS Interopdart migrate, dart run -e, NativeFinalizer.callback, rangeEquals, fast JS array & async Function.toJS conversions3.14 Reference
Dart 3.13Language & RuntimePrimary constructors, this constructor body, new/factory shorthands, Future.pause, List.unmodifiableOf3.13 Reference
Dart 3.12Language & ToolingPrivate named parameters (Point({this._x})), RegExp spans, dart run <pkg>@<ver>3.12 Reference
Dart 3.11Platform & PubWindows Unix domain sockets, Workspace globs (pkgs/*), dart pub cache gc3.11 Reference
Dart 3.10Extensibility & CLIAnalyzer plugins stable, Hooks (native assets) stable, dart install, @Deprecated constructors3.10 Reference
Dart 3.9Analysis & PubAOT analysis server, git tag version solving, null-safety assumptions in flow analysis3.9 Reference
Dart 3.8Formatter & DocsDoc imports (@docImport), tall formatter trailing comma preservation, Iterable.withIterator3.8 Reference
Dart 3.7Language & FormatterWildcard variables (_), inference using bounds, tall style formatter default, legacy web deprecations3.7 Reference
Dart 3.6Language & PubDigit separators (1_000_000), Pub workspaces, dart pub bump3.6 Reference
Dart 3.0 – 3.5Foundation & Major FeaturesRecords, Patterns, Switch Expressions, Sealed Classes, Class Modifiers, Extension Types, Field Promotion, Wasm3.0–3.5 Reference
Dart 2.0 – 2.19Historical MilestonesSound 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

  1. Review Macros & Augmentations Guide.
  2. Wire original files with import augment 'foo.g.dart'; and augmentation files with augment library 'foo.dart';.
  3. Use augment class, augment void method(), and call augmented() to wrap original logic.

2. Working with Experimental Feature Flags

  1. Check if the feature has already graduated to stable in the active SDK before adding a flag.
  2. If experimental, configure analysis_options.yaml under analyzer.enable-experiment: [name].
  3. Pass --enable-experiment=name to dart run, dart test, flutter run, and flutter test.
  4. Ensure experimental code is isolated so production packages remain publishable on pub.dev.

3. Modernizing / Rescuing a Legacy Codebase

  1. Check current language version from pubspec.yaml environment block.
  2. If pre-2.12, read the Legacy Rescue Guide.
  3. Execute the 4-stage pipeline: syntax cleanup → sound null safety → dependency bump (sdk: ^3.5.0 or ^3.13.0) → Dart 3 modernization.

4. Answering "What's New in Dart X.Y"

  1. Identify the requested version.
  2. Read the corresponding reference document under references/.
  3. 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"

  1. Check the Language Feature Matrix and How to Find minSdk Guide.
  2. Specify the exact lower bound SDK constraint for pubspec.yaml (for example sdk: '^3.13.0').
  3. Explain if the feature is a language grammar feature (requiring language version update) or a core library API.
  4. Show how to verify using dart analyze.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.