docs/postmortems/Postmortem-AndroidX-plugin-migration.md
Status: draft
Owners: @mklim, @amirh, @dnfield, @hixie
Description: The flutter/plugins repo was updated with a breaking change to
resolve
flutter/flutter#23995. The
change migrated and deprecated Android dependencies in the plugins'
build.gradle files and required any apps using the plugins to also have Gradle
files that were either migrated or compatible with the AndroidX. Gradle errors
in hard-to-debug ways on Flutter apps broken by the change, without surfacing a
clear explanation or migration path to affected users. In addition this was a
known breaking change but originally incorrectly incremented the minor semantic
version number in 6/32 of the affected packages.
Component: flutter/plugins
Date/time: 2019-01-24 13:24 -0800
Duration: 4 days for the semantic versioning problem. 2 weeks for the confusing Gradle error.
User impact: Users pinned to the major version of firebase_analytics, firebase_database, firebase_messaging, firebase_storage, google_sign_in, and url_launcher were broken by pub despite deliberately trying to avoid any breaking changes. All other first party plugin users that try to use the latest major version are affected by the confusing Gradle error.
flutter create on the
stable channel. Links the error to the AndroidX migration and tags @mklim,
@amirh, and @dnfield.flutter create error on stable offline. Decide to republish the AndroidX
migration with a constraint so that users are on a version of flutter that
produces AndroidX-compatible Gradle files. pub
maintainers are contacted to remove the broken packages.flutter stable is
incoming. However his comment doesn't have details on all of the plugins to
downgrade and what versions to downgrade them to. User discussion continues on
this bug over the next 48 hours.build.gradle, which could have been generated by any Flutter
version including the current one and which also could have been manually
edited. Decide that the semver problem should be fixed by patching the 6
affected plugins with a revert and then incrementing them with a major bump
and the migration.It looks like the only issue filed for this directly has been flutter/flutter#27128.
An explanation and migration path exists in the CHANGELOG.md of each plugin, but this information is hard to find and the actual Gradle error is not helpful. Several bugs on GitHub have been filed from affected users.
flutter/plugins#1103, flutter/plugins#1115 migrated the plugins to support AndroidX instead of the original Android support libraries. See #23995 for more details, but in short the original support libraries are deprecated and not recommended for Android app development anymore.
This was a known breaking change and the changelog links to the official
migration steps. BUT
plugins that were greater than or equal to 1.0.0 weren't updated according to
pubspec's semantic versioning
philosophy. On
pub for packages < 1.0.0 the versioning is 0.major.minor+patch, and for >=
1.0.0 it's major.minor.patch. The AndroidX PRs universally incremented the
middle number, so any plugin that was already at or above 1.0.0 is being
incorrectly treated as non-breaking by pub. This caused the semantic versioning
issue.
In addition the breaking change was only surfaced in the CHANGELOG.md of each plugin, but resulted in breaking Gradle errors at runtime. These Gradle errors did not provide any obvious ways to debug the incompatibility.
flutter create templates
relatively quickly and cc'ed the relevant devs.build.gradle files produced by released versions of flutter create. Also
failed to verify that the Gradle errors mentioned AndroidX or were otherwise
easily understandable.flutter/plugins CI failed to verify that the new plugins could be used
with the template from flutter create on stable.flutter create and semantic versioning issues.flutter create template on the plugins
CI