Flutter compatibility policy

The Flutter team tries to balance the need for API stability with the need to keep evolving APIs to fix bugs, improve API ergonomics, and provide new features in a coherent manner.

To this end, we have created a test registry where you can provide unit tests for your own applications or libraries that we will run on every change to help us track changes that would break existing applications. Our commitment is that we will not make any changes that break these tests without working with the developers of those tests to (a) determine if the change is sufficiently valuable, and (b) provide fixes for the code so that the tests continue to pass.

If you would like to provide tests as part of this program, please submit a PR to the flutter/tests repository. The README.md file on that repository describes the process in detail.

Announcements and migration guides

If we do make a breaking change (defined as a change that caused one or more of these submitted tests to require changes), we will announce the change on our flutter-announce mailing list as well as in our release notes.

We provide a list of guides for migrating code affected by breaking changes.

Deprecation policy

We will, on occasion, deprecate certain APIs rather than outright break them overnight. Deprecations are not considered breaking changes, though the eventual removal of the deprecated feature could be (if it breaks any of the submitted tests).

Dart and other libraries used by Flutter

The Dart language itself has a separate breaking-change policy, documented on the Dart wiki.

In general, the Flutter team does not currently have any commitment regarding breaking changes for other dependencies. For example, it’s possible that a new version of Flutter using a new version of Skia (the graphics engine used by Flutter) or Harfbuzz (the font shaping engine used by Flutter) would have changes that affect contributed tests. Such changes would not necessarily be accompanied by a migration guide.