This page describes the process of updating flutter/packages after a stable Flutter release. Hotfix releases don't require any changes, since the auto-roller will update the pinned stable version, but full stable releases (roughly once per quarter) require manual updates to the repository:

  • The stable pin needs to be updated. The autoroller will open a PR, but because it includes a separate commit for every Flutter commit since the last stable, it will overwhelm the CLA check and it will fail. Either the CLA check can be overridden (which is safe since the source repo enforces the CLA), or a new manual PR can be made that updates the hash.

  • The Flutter Dart version mapping needs to be updated. The Flutter SDK releases page is a useful reference.

    • In addition to adding the new release, add the last bugfix version of the previous stable, for the next step.

  • The N-1 and N-2 legacy analysis tests need to be updated. We generally use the latest bugfix versions for these tests.

  • The minimum allowed Flutter version for the repo needs to be updated to the N-2 version. (We generally use .0 here, not the latest hotfix, under the assumption that there are not going to be analysis-breaking changes in a hotfix.)

    • This should ideally be done in the same PR as the previous step, since that is the point at which we no longer have any coverage of the previous minimum version.

  • All packages need to be updated to that minimum version. This can be trivially done with the repo tooling. E.g.:

    dart run script/tool/bin/flutter_plugin_tools.dart update-min-sdk --flutter-min=3.7.0

    • Per repo policy, we do not version-bump these changes, so the associated update-release-info command should use --version=next. A convenient way to run the update-release-info command on only the necessary packages is to make the update-min-sdk run its own commit, then use --base-branch HEAD^ --run-on-changed-packages to target only the packages changed in that commit.
    • This must be done in the same PR as the previous step, or CI will fail.

  • The release action should be updated to use the new stable.

Many of these steps can be done separately, but they can also be done in combined PRs (as few as one). As an example, 3.13 was done in two PRs: #4370 and #4371.

Issue Updates

Sweep all p: waiting for stable update issues, and update those that are now unblocked to indicate that they can now be addressed (removing the label).

For any that are about deprecated API usage, upgrade them to P1, and either find an owner for them or remove the owning team's triaged-* label, leaving a comment that the deprecated API usage needs to be removed ASAP to minimize future disruption to package clients.

  • The motivation for treating these as P1 is that many clients do not update their packages (in particular, their transitive dependencies) frequently, so the further in advance of the eventual API removal the publishing of an update is, the fewer clients will have build errors on future updates of Flutter.

PR Updates

Similarly sweep all p: waiting for stable update PRs and comment and remove labels as necessary.