[Feature request] pub upgrade prompts

[amirh]

For package updates that include breaking changes it can be sometimes useful to present the developer(package user) with a prompt showing a message provided by the package developer.

I think this would be useful when the change in the package requires more than just adjusting the code to a new API.

While the CHANGELOG is the official place to include such instructions the recent experience with upgrading flutter plugins to use AndroidX showed that many people don't always read these(e.g https://github.com/flutter/flutter/issues/27226 https://github.com/flutter/flutter/issues/27146 https://github.com/flutter/flutter/issues/27156)

What I envision is that we could include some breaking change message with the upgrade(in pubspec.yaml?) which will result in something like the following when running pub upgrade:

$ flutter pub upgrade
....
Upgrading battery to 0.3.0 requires migrating your app to use AndroidX, please follow the 
upgrade instructions here: <link>.

Do you still want to upgrade to battery to 0.3.0? [y/N]
(selecting no will pin battery to ^0.2.0)

The 2 use cases I think this might help with are:

1. A user has battery: ^0.2.0 in his pubspec, he sees there's a new major upgrade to the battery package, he goes to pubspec.yaml and changes to battery: ^0.3.0 planning on spending some time figuring out the new API changes. But instead he gets some obscure Gradle error he doesn't know how to deal with.
2. A user has battery: any. (yeah this is not recommended, but this happens in practice)

I believe this would be mostly useful for Flutter plugins where it is common to require some manual environment setup steps from the package users(e.g set up API keys, config Gradle, config Info.plist, etc...)

cc @kevmoo @mklim

[jonasfj]

Instead of duplicating information from the changelog in the pubspec, we could parse the changelog.

[mit-mit]

pub upgrade upgrades only to the next non-breaking version, so not sure how useful this would be in the current upgrade model!?

[amirh]

@mit-mit the 2 use cases I think this might help with are:

1. A user has battery: ^0.2.0 in his pubspec, he sees there's a new major upgrade to the battery package, he goes to pubspec.yaml and changes to battery: ^0.3.0 planning on spending some time figuring out the new API changes. But instead he gets some obscure Gradle error he doesn't know how to deal with.
2. A user has battery: any. (yeah this is not recommended, but it seems to be pretty common in practice)

[mit-mit]

Maybe an alternate solution is to actually represent the gradle dependencies as pub dependencies?

[mklim]

@mit-mit I think that would be good to have on its own in addition to this, but there's also so much that can go into making plugin updates potentially breaking that I think it would be hard to completely capture everything as a dependency graph in pub.

Off the top of my head:

• Dependent native apps needs to add new permissions for new plugin functionality.
• Dependent native code needs to add new or different plugin hooks to its lifecycle callbacks.
• The plugin API itself has changed in breaking ways.
• The plugin relies on a new minimum platform SDK version.
• Android only: Gradle scripts now have a higher minimum compileSdkVersion.
• Android only: New intent filters need to be manually set up in dependent app code.

This particular change involved Gradle dependencies, but there's a lot of confusing breaking plugin updates like this that don't.

[sigurdm]

Now we have dependabot parsing changelogs for us when upgrading through that.

But it would still be cool to have this as a feature in the pub client.