New annotation request: `@IntentToAddClassModifier.kFinal` (and others)

[matanlurey]

Starting at Dart 3.x+, we have class modifiers, yay!

I'd like a way to mark an intent to adopt a modifier in a future release, so that:

1. The analyzer can issue diagnostics that a to-be-added modifier will become breaking.
2. The user can ignore said issue (it's not a release blocker) and attend to it as they prioritize.

As a straw-man, I'd propose adding IntentToAddClassModifier to package:meta:

// meta.dart
import 'meta_meta.dart';

/// Annotation marking a class as soon-to-add the equivalent class modifier.
///
/// Tools, such as the analyzer, can provide feedback if
/// - the annotation is associated with anything other than a class
/// - the annotation is associated with a class `C` and the corresponding class modifier would be a static error 
@Target({TargetKind.classType})
enum IntentToAddClassModifier {
  kAbstract,
  kBase,
  kFinal,
  kInterface,
  kSealed,
  kMixin,
}

For example, I'd use it here: flutter/flutter#142937.

/cc @pq @srawlins (I wrote this here versus dart-lang/linter because of the need to re-use analyzer logic for modifiers).

[munificent]

As a counter-strawman, how about:

/// Put this on a class to indicate that it should no longer be used in an
/// `extends` clause. Extending a class with this reports a deprecated lint
/// warning. Eventually, the class will be marked `final`, `interface`, or
/// `sealed`.
@DeprecatedExtends

/// Put this on a class or mixin to indicate that it should no longer be used
/// in an `implements` clause. Implementing a class or mixin with this reports
/// a deprecated lint warning. Eventually, the class or mixin will be marked
/// `final`, `base`, or `sealed`.
@DeprecatedImplements

/// Put this on a class or mixin to indicate that it should no longer be used
/// in a `with` clause. Mixing in a class or mixin with this reports a
/// deprecated lint warning. Eventually, the class or mixin will be marked
/// `final` or`sealed`.
@DeprecatedMixin

/// Put this on a class or mixin to indicate that it should no longer be
/// directly constructed (i.e. have one of its generative constructors invoked
/// outside of a subclass's initializer list). Invoking a non-factory
/// constructor on a class with this annotation reports a deprecated lint
/// warning. Eventually, the class will be marked `abstract` or `sealed`.
@DeprecatedConstruct

[matanlurey]

Maybe, I just like the idea of using the existing documentation and names used in the modifiers.

[natebosch]

As a counter-strawman, how about:

I hope we don't have to repeat the same evaluation process as when we defined the modifiers.... But I'll add a proposal.

+1 for modeling the annotation API on the modifiers so authors only need to think once about how to express their intent. The transition from annotation to keyword is trivial do correctly.

-1 for using a k prefix on the names.

How about @willBeFinal, @willBeInterface, @willBeBase, @willBeSealed.

[parlough]

Yes please! Let's lean on user's existing understanding of the class modifier terms. That might not exist at the preferred/ideal levels yet, but that will slowly improve with time and tooling enhancements :)

Other than that, I like this idea!

[matanlurey]

Just to be clear k was to avoid having to understand how to make reserved words work, so I'm on board.

[jonahwilliams]

its my fault, I've got @matanlurey working down in the C++ mines so his brain is full of chromium style guide.

[pq]

How about @willBeFinal, @willBeInterface, @willBeBase, @willBeSealed.

I like this idea.

As for the diagnostic specifically, I feel like we've talked about reporting something like this before (maybe in relation to the @since annotation?) but can't recall now. @bwilkerson?

[bwilkerson]

I'll note that the comments on this thread are all about the form of the annotation, not the value of having such an annotation. I don't know whether that means that folks are generally in favor of the proposal, or whether it's just more fun to discuss the details. :-) I don't have a strong opinion yet, but I do have some questions.

This is very similar in some ways to deprecated in that it's warning of an upcoming breaking change. Are there other kinds of breaking changes that we should be considering at the same time?

How much value will this bring to users? How often are breaking changes like this being made? How many users are impacted by those changes? How much would advance notice help users migrate?

Are there better ways to help users migrate? Is there something we could do using dart fix or some other tooling that would be a better UX, and if so would it negate the value of these annotations?

If we were to add support like this, would we want to be able to use it in the dart: libraries to announce future breaking changes?

@lrhn

[parlough]

How much value will this bring to users? How often are breaking changes like this being made? How many users are impacted by those changes? How much would advance notice help users migrate?

Dart and Flutter both had a variety of breaking changes here for Dart 3 and annotations like these could have potentially helped users account for that earlier. A list of the SDK's changes this could have helped in Dart 3: https://dart.dev/resources/dart-3-migration#extends--implements (if the SDK could use package:meta :P).

I think in the short term, there's likely many packages created before class modifiers existed that haven't taken the step to tighten their class capabilities. This functionality could definitely help in that migration. However, after the ecosystem has been given a longer period to adapt, it does feel like the lint could slowly become less useful.

I see the longer term solution for new APIs is for developers to consider class capabilities earlier on (#54656). Sometimes we make the wrong decision though or project requirements change, so there will always be times we may need to retighten the class's capabilities and this issue's proposed functionality would still be useful.

If we were to add support like this, would we want to be able to use it in the dart: libraries to announce future breaking changes?

Consider the above, I do think that would be useful, same for the other annotations in package:meta =]

Are there other kinds of breaking changes that we should be considering at the same time?

I think another useful one that's been discussed a few times is @willBeRequired to indicate an optional named or positional parameter will be required in the future.