Breaking change: pubspec.yaml must contain a Dart SDK constraint

[mit-mit]

Background

Dart apps and packages often use a pubspec.yaml file to declare various metadata such as dependencies. It can also contain a Dart SDK constraint such as:

environment:
  sdk: '>=2.10.0 <3.0.0'

This expresses that the app/package requires a Dart SDK that is at least 2.10.0, and strictly less than 3.0.0. This is commonly used to express that the code uses a feature only available in more recent Dart releases, for example Dart 2.7 if using extension methods. The SDK constraint is documented here: https://dart.dev/tools/pub/pubspec#sdk-constraints

Currently it is allowed to omit this SDK constraint. In that case Dart interprets this as having a lower constraint that is the same as the version of the Dart SDK being used.

What is the change

We're making it an error for apps to have a pubspec.yaml that doesn't have this SDK constraint specified. Concretely, for a pubspec not containing the Dart SDK constraint, the pub/dart pub/flutter pub command will abort dependency resolution for apps and fail with an error like:

pubspec.yaml has no lower-bound SDK constraint.
You should edit pubspec.yaml to contain an SDK constraint:

environment:
  sdk: '>=2.10.0 <3.0.0'

Why are we making this change

For the Dart null safety feature we're relying on the SDK constraint to tell if a Dart app/package us using null safety semantics or not. Because of the current defaulting to current SDK version when the SDK constraint is omitted, this results in such projects being opted-in to null safety implicitly. This in turn results in lots of null safety errors.

Making the SDK constraint required ensures that all apps and packages are forced to make a choice about what Dart version they need.

Effect of the change

All existing pubspec.yaml files that don't contain an SDK constraint will start to see resolution errors. They will need to add an SDK constraint like this to their pubspec. After adding this they will continue to run as before.

environment:
  sdk: '>=2.10.0 <3.0.0'

Timeline

This change is blocking the progress on null safety, so the change will be made immediately in the Dart master channel (where the Dart 2.12 version is underway).

[mit-mit]

cc @jonasfj @leafpetersen @vsmenon @franklinyow

[mit-mit]

Posted to Dart announce: https://groups.google.com/a/dartlang.org/forum/#!topic/announce/TyaUVp4hXwU

[franklinyow]

cc @Hixie @matanlurey

[Hixie]

Rather than merely fail with an error that tells the user what to do, can we provide a command that will do it for them? Adding something to a YAML file is something eminently automatable. Maybe we should even do it automatically, like we do pub get automatically?

[jonasfj]

@Hixie I fear that having pub get modify your pubspec.yaml without prompts or a flag would be surprising behavior.

We could do a pub fix command, but it just seems a bit arbitrary. Also what else could/should it fix..

As for modifying YAML, it's not trivial, but we had a GSoC project create package:yaml_edit to make this easy. I think the hard part is designing a CLI interface for exposing this logic.

[bwilkerson]

We might want to look into adding a quick fix in the analysis server for this case.

[franklinyow]

marking this as Approved

[subzero911]

How about adding a key to pubspec: uses-null-safety: true instead of relying on constraints? As a user, I don't want to remember since which version you added a null safety.

[jonasfj]

As a user, I don't want to remember since which version you added a null safety.

I think the upside is that once migrated, you'll probably stop thinking about this. A boolean would instead continue to be a thing going forward.

[franklinyow]

Closing this as this is already in Dart 2.12