Consider hosting a "migration cookbook" (of sorts) to help with breaking changes

[matanlurey]

See #54947.

There are certain patterns that need to be followed to work around tricky breaking changes. Consider the following:

class Cow {
  void moo() {}
}

Later, we decide Cows should also be able to walk:

class Cow {
  void moo() {}
+ void walk() {}
}

This is a breaking change, because anyone who wrote:

class CowLikeApparatus implements Cow {
  @override
  void moo() {}
}

... now is missing an implementation of walk. It is non-obvious that someone could land a patch in advance:

class CowLikeApparatus implements Cow {
  @override
  void moo() {}

+ // TODO(name): Remove after <issue link>
+ // ignore: unnecessary_override
+ @override
+ void walk() {}
}

I suspect there are many such "tricky" cases that the larger Dart team has encountered over the years (including landing lints and hints) that are mostly tribal knowledge. It would be a shame if there wasn't a central place folks could reference to instead of having to re-discover best practices over and over.

[dart-github-bot]

Item	Details
Summary	Propose creating a "migration cookbook" to document best practices for handling breaking changes.
Triage to	area-documentation (high confidence)

(what's this?)