Proposal: package_incompatibilities.yaml in the Dart SDK

[jonasfj]

The general idea is that in the root of the Dart SDK we should introduce a package_incompatibilities.yaml file.
It should sit next to the existing version and revision files, and it should be explained in the README.md file.

The package_incompatibilities.yaml file should have the following form:

incompatibilities:
- package: foo
  ranges:
  - >=3.0.0 <3.1.0
  reason: |-
    Libraries opt-out of null-safety using language version marker.
- package: bar
  ranges:
  - 1.0.0
  - 1.2.0
  reason: |-
    Relies on APIs that were removed in Dart 3.0.0

In essences the file would allow SDK developers to declare specific package versions to be incompatible with future versions of the Dart SDK.

Behavior:

• If a package version matching package_incompatibilities.yaml is in pubspec.lock then using it is fine.
• Otherwise, dart pub get should never allow a package version matched in package_incompatibilities.yaml.
• If a conflict arises, then the "reason" from package_incompatibilities.yaml can be surfaced.

Use cases:

• We've removed a deprecated API or feature that only affects a few packages.
• We're using an experimental feature and published with SDK constraint ^3.1.0-dev instead of >=3.1.0-dev <3.1.0 (and we regret it because the experimental feature was changed).

---

Whether we'd frequently want to use this functionality I don't know, I recall a few cases where it would have been a nice tool. I don't envision us wanting to use this frequently or at scale.

Mostly, I'm writing this proposal, so that we can consider implementing it should become relevant in the future.

[LongXiangGuo]

It's sounds more like to verify the runtime error in the pub get phase, that's a good idea.

[dcharkes]

• We're using an experimental feature and published with SDK constraint ^3.1.0-dev instead of >=3.1.0-dev <3.1.0 (and we regret it because the experimental feature was changed).

That could be useful for restricting packages that implement a protocol that talks with the Dart SDK dart-lang/native#93.

If @bkonyi ever needs to do a breaking change to the vm_service again (hopefully never), It would also help there I believe.

[bkonyi]

If @bkonyi ever needs to do a breaking change to the vm_service again (hopefully never), It would also help there I believe.

I'm not sure it'd help with package:vm_service. The VM service target could be running on a version of the SDK that's compatible with the version of package:vm_service used by a client that's using an older SDK that would have an incompatible protocol version. I think this feature only helps cases where the protocol and package are used in the same runtime instance.

[dcharkes]

I'm not sure it'd help with package:vm_service. The VM service target could be running on a version of the SDK that's compatible with the version of package:vm_service used by a client that's using an older SDK that would have an incompatible protocol version. I think this feature only helps cases where the protocol and package are used in the same runtime instance.

Ah right, the vscode plugin contains an already compiled version of the vm_service protocol.

[dcharkes]

From discussion with @jonasfj

Use cases:

• We've removed a deprecated API or feature that only affects a few packages.
  • [native_assets_cli][native_assets_builder] Supporting version skew between SDK and build.dart native#93 (comment) is kind of a variant of this. We have a rolling window of what we support. We remove an old version of a feature periodically.
• We're using an experimental feature and published with SDK constraint ^3.1.0-dev instead of >=3.1.0-dev <3.1.0 (and we regret it because the experimental feature was changed).
• Formalizing Flutter's package pinning (sdk: flutter).