[Dart 3] Document general use of class modifier by Dart core libraries in Library Tour

[parlough]

A lot of Dart core libraries are introducing usage of class modifiers to limit various uses of them (extending, implementing, mixing in, etc). We should make users aware of this somehow, likely when introducing the core libraries themselves. It can link to other class modifier docs if necessary.

[MaryaBelanger]

I think the communication plan for all of the Dart 3 migration / breaking changes info is to add a "Dart 3 migration" page to dart.dev somewhere. I've added notes about this to the planning doc for that communication and am waiting to see if others think it fits.

I'm not sure who's in charge of creating that content though, will update.

[parlough]

That sounds good, thanks.

I however still see value in educating users of the possibility of these limitations, whether they are migrating or not, while they approach core library usage.

[MaryaBelanger]

List of affected APIs per library from the changelog:

• dart:core
• dart:collection
• dart:math

Possibly also relevant / should be called out: Existing classes that have been made mixin classes

[MaryaBelanger]

Note: the migration guide summarizes this a little (not a replacement for documenting in the library tour)

[MaryaBelanger]

3.1.0 library changes dues to class modifiers:

• [breaking change] Mark four more classes in dart:async as interface sdk#52334

[parlough]

Thanks for calling attention to that, looks like it was part of the 3.0.3 release. I opened a PR adding them to the migration guide - #5075

[MaryaBelanger]

@parlough Thanks for adding those 3.0.3 changes to the migration guide. Just want to re-confirm: you still think those and all the other core library changes should be documented in their sections in the Library Tour, correct?

I'm updating the title of this issue since documenting them in the migration guide could be misconstrued as solving the title as written, but lmk if you're thinking differently!

[parlough]

Thanks for updating that.

My thinking still is just adding a brief mention to the top or intro that it is something developers may come across when using built-in Dart APIs. Perhaps it will be less useful over time as users learn about class modifiers, but just want learners to be at least a little familiar before they come across related diagnostic messages.

Maybe it's not necessary with the diagnostic messages, but I feel it wouldn't hurt to prepare them for that. What do you think?