Add onReorder callback migration guide

[navaronbracke]

Description of what this PR is changing or adding, and why:

This PR adds a migration guide for PR flutter/flutter#178242 since that change is not supported by dart fix.

Issues fixed by this PR (if any):

Related to flutter/flutter#127901
Related to flutter/flutter#169878

PRs or commits this PR depends on (if any):

flutter/flutter#178242

[gemini-code-assist]

Summary of Changes

Hello @navaronbracke, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive migration guide to assist developers in transitioning from the deprecated onReorder callback to the new onReorderItem callback across various Flutter reorderable widgets. The guide clarifies the rationale behind this breaking change, which simplifies index handling, and provides clear, actionable steps for updating existing codebases, noting that dart fix cannot automate this particular migration.

Highlights

• New Migration Guide Added: A new markdown file, src/content/release/breaking-changes/deprecate-onreorder-callback.md, has been added. This document serves as a migration guide for the transition from the deprecated onReorder callback to the new onReorderItem callback in Flutter's ReorderableListView, ReorderableList, and SliverReorderableList widgets. It explains the rationale behind the change, which simplifies index handling, and provides clear code examples for migration.
• Clarification on Callback Behavior: The guide details how the onReorderItem callback automatically handles the newIndex correction that was previously required manually with onReorder, thus simplifying the logic for developers. It explicitly states that this migration is not supported by dart fix due to the change in the meaning of the second callback parameter.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a well-written and clear migration guide for the onReorder callback deprecation. The document effectively explains the background of the change, provides a step-by-step migration process, and includes helpful code examples for all affected widgets. This will be a great resource for developers. I have one minor suggestion to make the document slightly more concise.

[dkwingsmt]

Some minor suggestions. Take whichever you see fit. LGTM overall. Thank you!

[parlough]

/gcbrun

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 9fc0db9):

https://flutter-docs-prod--pr13012-deprecate-reorder-callback-1aevc57i.web.app

[navaronbracke]

@dkwingsmt I adjusted the migration guide based on your feedback and made some other fixes as well.

1. I added a case that mentions the "opt-out"
2. The guide now uses one widget as example
3. I put the note about dart fix not being supported in an info box, similar to the one at the top of the document
4. I tried to add a diff view (+/-) in the code samples, to highlight the changes in the migration (this was a bit tricky, since you need to indent the entire sample by 2 spaces and then add the +/- in place of the very first space on every line)

@parlough Can we rerun the docs page again? I'd like to verify if my new formatting changes are good.

[dkwingsmt]

/gcbrun

[sfshaza2]

Just making sure that everything still builds:
/gcbrun

[sfshaza2]

/gcbrun

[sfshaza2]

lgtm

[navaronbracke]

Do I update the index file in this pull request, once I get a second approval?

[navaronbracke]

FYI: The index file was updated to include the breaking change document

[sfshaza2]

/gcbrun

[sfshaza2]

@navaronbracke, can you email me at shaza@google? thx!

[navaronbracke]

What should be included in the email? The markdown document?

[sfshaza2]

LOL. Nope, I will recognize your name. :D

[navaronbracke]

Mail sent :)

[gbolahan507]

@navaronbracke, Please, can you review my PRs, as this keeps me going.

flutter/flutter#181974
flutter/flutter#181951
flutter/flutter#181903

[navaronbracke]

Please don't ask for reviews of unrelated things in different issues / PR's. If you have open PR's those will be reviewed eventually, but you need to have patience to let reviewers do their work.