search

dart-lang / site-www

Source for Dart website
https://dart.dev
Other
936 stars 675 forks source link

Changed all sdk refs to use caret syntax #5864

Closed atsansone closed 1 month ago

atsansone commented 1 month ago

Fixes #5863

dart-github-bot commented 1 month ago

Visit the preview URL for this PR (updated for commit 9ecc21980d0dc01f376eaaf8ff62e918b67de85f):

https://dart-dev--pr5864-fix-5863-olxtjijj.web.app

atsansone commented 1 month ago

@parlough : Dart supported caret syntax since Dart 1.24.3: https://github.com/dart-lang/pub/issues/2153

@kevmoo verified and asked that it be done.

parlough commented 1 month ago

@atsansone https://github.com/dart-lang/pub/pull/3672 landed in Dart 2.19. So users with an SDK before 2.19, will get an error when pub runs SDK validation with a caret SDK constraint. From my reading of the issue, caret syntax was technically supported but the tool explicitly added an error.

Versions before 2.19 are meant to be supported by many of these mentions, or are even the focus.

natebosch commented 1 month ago

There was some confusion between allowing ^ constraints for environment: sdk: keys, vs dependencies: package_name: keys, or environment: flutter: keys.

For

environment:
  sdk:

We should only use ^ if the constraints is >=2.19 <3.0 or higher.

We should not use ^ for any environment: flutter: keys.

A well formed and idiomatic pubspec will look like either of

environment:
  sdk: ^3.3.0
  flutter: '>=3.19.0'

or (for older SDKs)

environment:
  sdk: '>=2.18.0 <4.0.0'
  flutter: '>=3.3.0'

It has been the case for a long time that dependencies: package_name: keys use ^ in most idiomatic pubpsecs.

sigurdm commented 1 month ago

technically supported but the tool explicitly added an error.

Just to clarify: the error is only there when validating before publishing. Since dart 1.8 we can consume the caret syntax, also in sdk constraints.

atsansone commented 1 month ago

@sigurdm , @natebosch , @natebosch , @kevmoo : OK, this is really, really confusing. Let's review.

  1. Dart, since 1.8, can consume the caret syntax.
  2. The SDK constraint validator returns an error when an upper bound constraint is not provided.
  3. The SDK constraint validator doesn't have an issue with the caret syntax with 2.19 or later.
  4. The SDK constraint validator error doesn't affect the dependency graph in any substantive way.
  5. The preference, expressed by @kevmoo and @jonasfj , is to use the caret syntax.
  6. Flutter can't support the caret syntax and doesn't want an upper bound constraint.

This content should stay the same for anything with a constraint of 2.18 or earlier because the SDK constraint validator for those versions will return errors when the caret syntax is used.

sigurdm commented 1 month ago

Yeah the sdk constraints story is a bit muddled.

A few inline comments to expand a bit on your summary.

Dart, since 1.8, can consume the caret syntax.

Yes.

The reason that the caret syntax was not used with the Dart sdk constraint from the beginning was to provide backwards compatibility (older pubs would not look at the rest of the pubspec after they decide.) When looking into this while trying to find a solution for allowing caret sdk constraints when publishing to pub dev we found out that this was not working correctly - old pub would anyway read the entire pubspec from the package listing api and crash.

So we removed that restriction and allowed caret syntax in the dart sdk constraint from dart 2.19

The SDK constraint validator returns an error when an upper bound constraint is not provided.

This is for the Dart sdk constraint. The Flutter sdk constraint is different. Here we ignore the upper bound.

Basically for marketing reasons it was decided to release flutter 2.0.0 without breaking backwards compatibility with flutter 1.x.x. To facilitate this it was decided that the Flutter constraint would ignore the upper bound. (ie. flutter is not strictly following semver, instead following https://docs.flutter.dev/release/compatibility-policy.)

The SDK constraint validator error doesn't affect the dependency graph in any substantive way.

Correct.

The validator is only attempting to provide best-practice guidance before publication.

We had a corresponding check on the pub.dev server rejecting packages with a caret dart sdk constraint. That has been removed.

The preference, expressed by @kevmoo and @jonasfj , is to use the caret syntax.

Yes, use the caret syntax for all your package dependencies, and for the dart sdk. That is usually the right thing (works with this version, and any later non-breaking version).

Flutter can't support the caret syntax.

You can also use the caret syntax for the flutter sdk constraint, but if you do, the upper bound will just be silently ignored. The flutter team strives for maintaining backwards compatibility forever, and offers to help out and provide migration tools when that is not possible.