Data-driven fixes

As a package maintainer, modifying or deprecating public APIs can break existing code for your users. To help your users upgrade smoothly, you can provide data-driven fixes.

Data-driven fixes are declarative migration rules stored directly within your package. After users update to a newer version of your package, they can apply these migrations with dart fix or IDE quick fixes.

To provide automated migrations for your package, follow these steps.

Add a file named fix_data.yaml to your package's lib/ directory:

If you have many fixes, you can split them across multiple files in a lib/fix_data/ directory.

In fix_data.yaml, specify the format version (version: 1) and a transforms list. Each transform describes the API element that changed and the changes to apply.

For example, if you rename oldMethod() to newMethod() in class MyClass:

version: 1
transforms:
  - title: 'Rename oldMethod to newMethod'
    date: 2026-09-18
    element:
      uris: ['my_package.dart']
      method: 'oldMethod'
      inClass: 'MyClass'
    changes:
      - kind: 'rename'
        newName: 'newMethod'

• date: A YYYY-MM-DD date indicating when the change was introduced.
• uris: A list of library URIs that export the API, relative to the lib/ directory, such as 'my_package.dart'.

To ensure your migration rules work as expected, set up paired test files and golden files that contain the expected code after applying the migrations.

Create a test_fixes/ directory in your package root:

• my_api.dart: Code written against the old API.
• my_api.dart.expect: The expected code after applying dart fix.

For example, pair your test files as follows:

import 'package:my_package/my_package.dart';
​
void main() {
  MyClass().oldMethod();
}

import 'package:my_package/my_package.dart';
​
void main() {
  MyClass().newMethod();
}

From your package root, run dart fix with --compare-to-golden:

$ dart fix test_fixes --compare-to-golden

If the output matches your .expect file, the command exits with code 0. If there is a difference, it displays a diff and exits with a non-zero code, making it ideal for CI test suites.

To learn more about all supported change kinds (such as parameter modifications and replaced declarations), conditions, and code templates, see the Data-driven Fixes specification.