Per the wiki:

Deprecation

Old APIs can be marked as deprecated as part of this process. Deprecation is not a way to avoid making a breaking change; you should consider deprecating an API to be equivalent to removing it, as some of our customers (and we ourselves) consider using a deprecated API to be anathema (triggering a build failure).

The syntax for deprecations must match the following pattern:

@deprecated(
'Call prepareFrame followed by owner.requestVisualUpdate() instead. '
'This feature was deprecated after v1.7.3.'
)
In other words:

@deprecated(
'[description of how to migrate] '
'This feature was deprecated after [dev version at time of deprecation].'
)
Using this standard form ensures that we can write a script to detect all deprecated APIs and remove them. We have a test that verifies that this syntax is followed.

When deprecating features, be aware that you will not by default be informed when the Flutter code itself uses the deprecated feature. To find places where the old feature is used, rename its declaration and see where the compiler complains.

This policy does not require that deprecated features be removed promptly, nor does it require that we limit the use of deprecations. While you are encouraged to please use moderation and judgement in deciding to deprecate something, there is no quota, and there is no time limit to how long a deprecated feature may remain supported before it is removed. We will, at a later time, introduce a policy for removing deprecated features, in a "first-in-first-out" fashion (this is why the syntax required here mentions a version number).

This missing portion of policy regarding removal needs to be defined. It should involve clearly communicating expectations to developers as to when a deprecation will be removed, and also make it easy to parse for valid deprecations to remove.