Repository navigation
Link migration guide in deprecation messages - #195361
Merged
Merged
Conversation
github-actions
Bot
added
c: contributor-productivity
justinmc
commented
Oct 26, 2026
Comment on lines
523
to
526
| Removing deprecated APIs from the framework are not currently planned. In the past, deprecations were removed after a set | ||
| amount of time. This is not currently in practice. If and when we do resume removing deprecated APIs, it will be announced | ||
| across several channels like the [flutter-announce group](https://groups.google.com/g/flutter-announce), and the | ||
| [Discord](../contributing/Chat.md). |
Contributor
Author
There was a problem hiding this comment.
This paragraph is something else we might want to update, but let's wait until we have a solid plan.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the Tree-hygiene.md documentation to specify that deprecation messages must provide clear migration steps, typically by linking to a migration guide. It updates the @Deprecated syntax pattern and example to include a placeholder for the migration guide link. The review feedback suggests clarifying that a link to the migration guide should be included rather than the guide itself, and marking the migration guide link placeholder as optional where applicable.
| @Deprecated( | ||
| '[description of how to migrate] ' | ||
| '[brief motivation for why we are breaking the API] ' | ||
| '[link to the migration guide] ' |
Contributor
There was a problem hiding this comment.
Since not all deprecations require a full migration guide (e.g., simple renames or trivial replacements), we should indicate that the migration guide link is optional or only applicable when a guide exists.
Suggested change
| '[link to the migration guide] ' | |
| '[link to the migration guide, if applicable] ' |
Contributor
Author
There was a problem hiding this comment.
I say leave this as-is. I don't want to give people an out. The vast majority if not all deprecation messages should have a migration guide IMO.
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
github-actions
Bot
added
the
tool
| testWithoutContext( | ||
| 'Plugin parsing rejects sharedDarwinSource without pluginClass or ffiPlugin', | ||
| () { | ||
| final fileSystem = MemoryFileSystem.test(); |
Contributor
There was a problem hiding this comment.
Why are changes in this file needed, they seem unrelated.
Contributor
Author
There was a problem hiding this comment.
I thought that was going to go away with a merge, let me rebase...
justinmc
force-pushed
the
justinmc-deprecation-migration-guides
branch
from
October 26, 2026 23:09
1ac968b to
95655d7
Compare
github-actions
Bot
removed
the
tool
justinmc
added
the
autosubmit
flutter-dashboard
Bot
removed
the
autosubmit
This was referenced Oct 27, 2026
auto-submit Bot
pushed a commit
to flutter/packages
that referenced
this pull request
Oct 28, 2026
flutter/flutter@d4c8577...0c2473c 2026-10-28 [email protected] Roll Packages from a8549ae to 13d38e0 (9 revisions) (flutter/flutter#195488) 2026-10-28 [email protected] Use int.oneBitCount in PersistentHashMap and scope 53-bit caps to JS (flutter/flutter#195005) 2026-10-28 [email protected] Roll pub packages (flutter/flutter#195483) 2026-10-28 [email protected] [iPhone Duo] Use the correct UIScreen to report the display size and update when fold/unfold (flutter/flutter#195199) 2026-10-28 [email protected] [fuchsia] Fix portable_ui_test.h includes for newer Fuchsia SDKs (flutter/flutter#195420) 2026-10-28 [email protected] Change default pipeline options to match production draw calls (flutter/flutter#194597) 2026-10-28 [email protected] Roll Fuchsia Test Scripts from 2T18KC7-LDQtmQiLP... to xl1LWBuppzu-BnOzV... (flutter/flutter#195450) 2026-10-27 [email protected] [flutter_tools] Inject dependencies into Darwin build targets, native assets, and Xcode build settings (flutter/flutter#194052) 2026-10-27 [email protected] Revert: Reland square corners fix (flutter/flutter#195436) 2026-10-27 [email protected] [flutter_tools] Add DeviceService app launch and flutter run support for tool extensions (flutter/flutter#194589) 2026-10-27 [email protected] [engine] Honor targetWidth/targetHeight for animated images (flutter/flutter#194615) 2026-10-27 [email protected] [Android][a11y] Set visibleToUser=false for hidden semantics nodes (flutter/flutter#194411) 2026-10-27 [email protected] Fix repo deletion test flake (flutter/flutter#195349) 2026-10-27 [email protected] Roll Packages from 23a05b6 to a8549ae (10 revisions) (flutter/flutter#195434) 2026-10-27 [email protected] [web] Capture pointers to the Flutter view so drags survive platform view iframes (flutter/flutter#195187) 2026-10-27 [email protected] [web] Add opt-in raw samples, measured sample count and warm-up phase hook to the web benchmark recorder (flutter/flutter#195118) 2026-10-27 [email protected] Link migration guide in deprecation messages (flutter/flutter#195361) 2026-10-27 [email protected] Pin basic_material_app_macos__compile to macOS 26 (flutter/flutter#195429) 2026-10-27 [email protected] Add benchmark for warmed pipeline usage (flutter/flutter#195001) 2026-10-27 [email protected] [flutter_tools] Add device log streaming support to DeviceService and ExtensionBackedDevice (flutter/flutter#194964) 2026-10-27 [email protected] Roll Dart SDK from 1d16c04dc346 to 65fc979759ca (4 revisions) (flutter/flutter#195383) If this roll has caused a breakage, revert this CL and set the roller to dry run mode using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
suryaKommana2662
pushed a commit
to suryaKommana2662/flutter
that referenced
this pull request
Oct 29, 2026
This PR updates our [Tree Hygiene wiki page](https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#deprecations) to say that we should include a link to the migration guide inside of deprecation messages. This was decided in order to help agents (and regular ol' humans) discover how to migrate deprecated code. See flutter#194592 for more information. FYI @jakemac53 --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR updates our Tree Hygiene wiki page to say that we should include a link to the migration guide inside of deprecation messages.
This was decided in order to help agents (and regular ol' humans) discover how to migrate deprecated code. See #194592 for more information.
FYI @jakemac53