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

Presubmit checklist

• If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.

• If this PR is not meant to land until a future stable release, mark it as draft with an explanation.

• This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).

• This PR uses semantic line breaks
  of 80 characters or fewer.

  cc @dkwingsmt

[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.

[gemini-code-assist]

This render of main-api.md appears to be redundant. It's already included on line 159, before the lists of links it applies to. Including it a second time here is unnecessary and can be removed along with the following blank line to improve conciseness.

[navaronbracke]

I do not see this macro in other breaking change documents. I have remove it from the PR, but can a writer double check if I need to omit it, or keep it somewhere?

[dkwingsmt]

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

[dkwingsmt]

I think we don't need to enumerate all 4 cases. Taking one of them for example is clear enough.

[navaronbracke]

I decided to add all sample variants, since all of these widgets need the migration.

I think that is clearer for someone who needs to migrate a lot of code that is affected?
I'm fine with keeping these or removing them, but I would prefer being a little verbose here, for the sake of the reader.

[dkwingsmt]

It might be helpful to provide an extra version that explains "what if your current onReorder doesn't have that if clause".

[navaronbracke]

Added an example that defers onReorder to a callback function to show what to do then.

[dkwingsmt]

I'm not sure what this is used for... I was probably misunderstood. What I meant was:

If the current onReorder doesn't use the said if clause, migrate it in this way:

Code before migration:

ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    ...
  }
)

Code after migration:

ReorderableListView(
  onReorderItem: (int oldIndex, int newIndex) {
    if (oldIndex < newIndex) {
      newIndex += 1;
    }
    ...
  }
)

[navaronbracke]

The point of the new onReorderItem is that you do not need the

if (oldIndex < newIndex) {
      newIndex += 1;
}

in your onReorderItem callback, because it is done for you inside the widget.

If you did not have

if (oldIndex < newIndex) {
      newIndex += 1;
}

anywhere in your onReorder callback, then you actually had a bug in your code (this is why people probably filed issues on Github, because they forgot to add it?)

There was a note in the docs about this before (which I now removed, since it no longer applies with the new callback)

https://github.com/flutter/flutter/pull/178242/changes#diff-23a4bb073009d89f09084bdf5f85232de135b8f11be625e6312bb85900a90e67L41-L44