breaking change: static error when importing dart:mirrors on the web

[sigmundch]

This change is to make it a static error to import dart:mirrors on dart2js and DDC.

Previously, dart:mirrors was deprecated on Dart for the web since 2.0.0 and both compilers provided empty implementations that throw on every single API. We are changing the behavior from a runtime error to a compile-time error.

What can break?

An app or test that imports dart:mirrors directly or indirectly, where mirrors is practically unused, and that is only compiled via dart2js, could see this breaking change. After this change such app will now see a compile-time error and not build.

Many of our tools, such as webdev and flutter, already disallow using dart:mirrors. Developers working on top of webdev using DDC already see a compile-time error if dart:mirrors is imported on their application. Flutter web also provides a static error today.

For this reason, we believe the majority of users won't be affected by this change. Only those that directly access dart2js or DDC without any additional frameworks, or that run dart2js test directly via package:test, are potentially affected. We also know from an earlier accidental breaking change that only 2 users have been affected and both have been able to circumvent this breaking change already.

Note also that packages that use dart:mirrors are already tagged in pub.dev as Native-only and not compatible for the web.

Mitigation

Apps that show a compile-time error need to remove the import to dart:mirrors. This may require changing dependencies on packages or fixing upstream packages to avoid the import. Some ways to remove the dependency is to hide it behind a conditional import. Package authors can also create a separate library in their package, so only those that need the functionality purposely import the dependency on mirrors.

@franklinyow @mit-mit @vsmenon @kevmoo

@Hixie @matanlurey for approvals

[vsmenon]

lgtm

[jonasfj]

It might be worth mentioning that it is possible to work around this using conditional imports.
Using conditional imports will also make platform classification on pub.dev work correctly.

Another convention is to move code that depends on mirrors to a separate library.
For example, such code could be moved to lib/mypkg_mirrors.dart, while keeping generic logic in lib/mypkg.dart.

[franklinyow]

ping @Hixie @matanlurey for approval

[Hixie]

sgtm

[matanlurey]

lgtm

[franklinyow]

Approved

[sigmundch]

Thanks All

@jonasfj thanks for the suggestions, I added them to the mitigation section above to increase their visibility. The breaking change landed in c632a62 and will be part of the 2.9.0-21.10.beta release and the upcoming stable 2.9 stable release.