Can the `@Since` annotation be made usable for packages?

[rrousselGit]

The SDK uses a custom annotation for warnings: @Since('version').

This warning is helpful to help folks with changing their version constraints to match what they use in their application.
This is especially useful in Dart as it is installed globally instead of on a per-project basis. But there are other use-cases.

I think opening this annotation to Flutter and package authors would be helpful too.

In general, it is very difficult to know what is the actual minimum version possible of a dependency based on what a package uses.
A package may specify dependency: ^1.0.0, yet use a feature only available since v1.2.0 – because when the package was first developed, 1.2.0 was available.

As such, the package author may think their package is compatible with dependency: 1.1.0, when it actually isn't. So if an application depends on our package but also uses an older dependency version, it will get a funky compilation error (in the best-case scenario) instead of pub failing to resolve the pub get.

By opening up this annotation to package authors, folks could start annotating new APIs with @Since when they are introduced. This would help the community as a whole deal with minimum version constraints.

[lrhn]

We can make the Since class from the platform libraries public, likely in dart:core, or we can introduce a new declaration in package:meta.

The latter requires an extra dependency to use. The former exposes an annotation that has no language effect, and it's only used by the analyzer. But that goes for all other public annotations in dart:core too. Which is really just deprecated, the override should have been in package:meta too.

The Since annotation is about versioning, just like deprecated, so it does fit the theme.

[rrousselGit]

Note that it appears to be quite common for package authors to forget to bump their minimum constraints.

Since I've started running pub downgrade in my CIs to check that I didn't forget to bump my min constraints, I've found that numerous dependencies also forgot to do so too.
For example, today I found that mockito forgot to bump their minimum analyzer version. dart-lang/mockito#656

This forces me to fix versions of transitive dependencies on my own in my packages, by listing them as dev_dependencies with the necessary version.

There's an example in one of the repositories I'm working on: https://github.com/invertase/dart_globe/blob/main/packages/globe_cli/pubspec.yaml#L30

[lrhn]

Changing to be an analyzer issue, because the question is whether the analyzer is interested in checking Since annotations in package code. If so, making the annotation public would be fine.

The behavior would be similar to the SDK:

• A declaration would be annotated with @Since("X.Y"), which should be no greater than the current version of the current package, as written in pubspec.yaml.
• A reference to/use of that declaration from another package would cause a warning, unless the minimum version constraint on the providing package is at or above "X.Y.0".
• If the package doesn't have a minimum constraint on the package of the declaration it's using, meaning it's not depending directly on that package, it's probably because the declaration is exported by another package. We'd have to figure out which minimum constraint to use in that case. (I'm guessing a simple heuristic will be enough most of the time, say "minimum required version by any directly depended on package which directly depends on the declaring package, and if that fails, continue a breadth first search on direct dependencies." It must come from somewhere, and likely just from one other package.)

It's not perfect for indirect dependencies, because it still depends on the current version solution. Optimally, it should depend on the result of pub downgrade. Hopefully indirect dependencies are rare enough that it's not a big issue.

[rrousselGit]

About the package exporting another package issue:
Maybe export statements could have a "since" annotation?

Like:

// package:foo/foo.dart
export 'package:bar/bar.dart'
  show
    @Since('1.0.0')
    Bar,
    @Since('1.1.0')
    barUtil;

This should enable packages to "override" the @since for their use-case.

[rrousselGit]

Ideally, we would also have a CI tool which, by relying on either pub or git, checks for missing @since statements.

Like maybe a custom pub publish rule.

[lrhn]

About the package exporting another package issue:
Maybe export statements could have a "since" annotation?

I'd actually want that syntax for saying when the export was added, in the current package's versioning.
(Probably can't put annotations on individual show clauses, but you can have multiple exports of the same library.)

That still leaves us without a way to say which version of the exported library we're promising.
Maybe a modifier to the annotation:

@Since("1.2") // The version of my own package where this export was added.
@Since(package: "foo", "3.3"),  // The expected library version of the exported package.
export  "package:foo/foo.dart";

(Very loose thought, not sure whether it'd work.)

[rrousselGit]

I think show-based @Since is quite valuable.

Because a more legitimate use case may be one package having multiple public libraries, both exporting the same private library, but with different shows/hides.

Like:

// my_package/lib/a.dart
export 'src/file.dart' 
  show
   // This library exports Foo since 1.0.0
    @Since('1.0.0')
    Foo;

// my_package/lib/b.dart
export 'src/file.dart'
   show
      Bar,
      // "Foo" is exported by this library only since v1.2.3
     @Since('1.2.3')
      Foo;

In this case, although the class Foo existed since v1.0.0, the import package:my_package/b.dart only exports Foo since v1.2.3

[keertip]

cc @bwilkerson

[bwilkerson]

... the question is whether the analyzer is interested in checking Since annotations in package code.

If we can fully define the semantics of the annotation when used outside the SDK (there are some interesting ideas above, we just need to know which are actually being supported) I wouldn't have any problem having the analyzer check for it. The analyzer already produces warnings related to the other annotations exposed from the core libraries.

I think show-based @Since is quite valuable.

The language grammar allows annotations on directives, but doesn't allow annotations on the names in a show clause. In order to change the parser to recognize these annotations we'd probably need a minor adjustment to the language. I doubt that it would create any issues, but it can't really be an analyzer-only enhancement; I think it really does need to be added to the spec for all tools.

[lrhn]

The grammar not allowing annotations inside the declaration was the main reason I suggested having multiple exports if you need multiple versions mentioned.

To actually work, each such annotated exported declaration should probably only be exported by one export.

[sigurdm]

cc @jonasfj who has been thinking about this.