Handling package retraction

[Reprevise]

When a package gets retracted, there is little tooling to get back to a supported version, which is semi-fair considering how rare it is. However, when it does happen, it's annoying. I'm proposing a couple of things.

• Highlight retracted versions in pub outdated
  • Currently, the only way you can tell a package is retracted is noticing your current version is ahead of the one shown in the "Latest" column
• Add some way to get back to the supported version
  • The "easiest" way I know how is running pub downgrade then running pub upgrade again

Other questions
How does pub cache handle reverts? Would I have to delete the folder in the cache for the reverted version if the author were to re-use the same version?

[sigurdm]

I agree pub outdated could show something. We do that for discontinued. That is probably an oversight.

How does pub cache handle reverts? Would I have to delete the folder in the cache for the reverted version if the author were to re-use the same version?

We don't delete the version from the cache. You are still free to use it if it is in the pubspec.lock.
You cannot reuse a retracted version number.

[Reprevise]

So what about going back to a non-retracted version? I can agree it's pretty rare (though this is just an anecdote, some metrics on this would be interesting), but would it be worth adding a way to go back easily? Using pub upgrade doesn't make sense, and pub downgrade AFAIK goes to your min version constraint.

[sigurdm]

dart pub upgrade should get you to the latest non-retracted version (that is compatible with other dependencies...)
If you want to go to a specific version (without changing your constraint) you pretty much have to edit pubspec.lock manually. (Remember to do dart pub get after editing the pubspec.lock, it will warn you about the content-hash not matching, and update pubspec.lock with the correct hash).

[sigurdm]

Another way would be to add a "pinning" constraint in pubspec.yaml (so a dependency on a specific version), that can be done with dart pub add packge:version, and then reverting the change in pubspec.yaml, but not pubspec.lock.

I think this case is rare enough, that we don't need commands for it. Manually editing the pubspec.lock is not that hard IMO.

[Reprevise]

dart pub upgrade should get you to the latest non-retracted version (that is compatible with other dependencies...)

I don't recall dart pub upgrade going back to a non-retracted version when it happened to me. Something to look into maybe?

[sigurdm]

I don't recall dart pub upgrade going back to a non-retracted version when it happened to me. Something to look into maybe?

By "latest" I mean newest. In most cases there will be a newer version than the retracted one available. Only if no such version exists upgrade should downgrade you.

[Reprevise]

By "latest" I mean newest. In most cases there will be a newer version than the retracted one available. Only if no such version exists upgrade should downgrade you.

So you're saying, if the package author hasn't published a version after the retracted one, then pub upgrade should downgrade? I don't recall that happening to me, unless I have to specify the package name specifically like pub upgrade {package}.

[sigurdm]

I don't recall that happening to me

I just confirmed this. I thought upgrade would always steer away from retracted versions if possible, but it actually allows the current version to be retracted. This makes sense for pub get. But pub upgrade should not keep locked versions?

@szakarias is this what we want?

The following test confirms this:

import 'package:test/test.dart';
import '../descriptor.dart' as d;
import '../test_pub.dart';

void main() {
  test(
      'Upgrade will downgrade if current version is retracted, and no newer versions exists',
      () async {
    final server = await servePackages();
    server.serve('foo', '1.0.0');
    server.serve('foo', '1.5.0');
    await d.appDir(dependencies: {'foo': '^1.0.0'}).create();
    await pubGet(args: ['foo'], output: contains('+ foo 1.5.0'));

    server.retractPackageVersion('foo', '1.5.0');
    await pubUpgrade(output: contains('< foo 1.0.0'));
  });
}

Fails with

  Expected: contains '< foo 1.0.0'
    Actual: 'Resolving dependencies...\n'
              '  foo 1.5.0 (retracted)\n'
              'No dependencies changed.'
     Which: does not contain '< foo 1.0.0'

[szakarias]

In the documentation https://dart.dev/tools/pub/publishing#retract we strongly encourage to publish a new version before retracting so I would think that in most cases there is a new version.

In this (hopefully rare) case, we could consider downgrading if possible.

[sigurdm]

Question is how hard it would be to implement. If I remember correctly we currently leave retracted versions out if the solve entirely unless:

• they are currently locked or
• they are pinned

If we want to implement the potential downgrade (downgrade unless no older versions exist) we would have to change the prioritization of retracted packages, and that would be a heuristic at most (not guaranteeing that we get the lower version)...

[szakarias]

It's not just a matter of implementation. There are many corner cases to consider when there is no newer version available. I am not sure we want this downgrade, because it cannot solve all these cases. I might be better to consider ways to advise users how to migrate away from retracted versions.

[szakarias]

We've decided that we don't want to do downgrading at this point. We will be adding some documentation on which flows you can use to migrate away from retracted versions when no newer version exists.

Basically you can either do pub downgrade foo followed by pub upgrade foo or you can manually delete the package entry in pubspec.lock and then do pub get or pub upgrade. You can also completely delete pubspec.lock but then you might also get version changes for other dependencies.

The documentation is tracked here dart-lang/site-www#5315

[Reprevise]

Well, I still think that retracted versions should be pointed out by the pub tool. Perhaps it can also link to the new documentation in the case that you're on a retracted version of a package too.

[szakarias]

I agree, it should also be pointed out in pub outdated so I'm not closing this issue.

[sigurdm]

Btw. this is related to an earlier issue: #3887