docs: add migration guide for findChildIndexCallback of separated builder #12636

rkishan516 · 2025-11-05T02:05:17Z

This PR add breaking changes migration guide for findChildIndexCallback of seperated builders in ListView and SliverList.

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.

gemini-code-assist · 2025-11-05T02:05:34Z

Summary of Changes

Hello @rkishan516, 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 essential documentation for a breaking change in Flutter's list widgets. It provides a clear migration guide for developers transitioning from the deprecated findChildIndexCallback to the more intuitive findItemIndexCallback in ListView.separated and SliverList.separated. The new guide aims to reduce confusion and errors by explaining how the new callback directly handles item indices, thereby simplifying code that previously required manual adjustments for separators.

Highlights

Documentation Update: A new migration guide has been added to the breaking changes documentation, specifically addressing the deprecation of findChildIndexCallback in ListView.separated and SliverList.separated.
API Migration Guidance: The guide details the transition from findChildIndexCallback to the new findItemIndexCallback, which simplifies index calculations by directly returning item indices and removing the need for manual adjustments to account for separators.

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.

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 PR adds a helpful migration guide for the findChildIndexCallback deprecation. The explanation is clear and the code examples are useful. I've found a few issues to address:

There's a typo in the new markdown file's name (seperated should be separated). This typo is also present in the link within index.md and the PR title.
The "after migration" code examples for both ListView.separated and SliverList.separated are incorrect. They should return null when an item is not found, but they currently return -1.
There's a missing link definition for ChildIndexGetter in the new migration guide, which will cause a broken link.

Please see my detailed comments for suggestions on how to fix these.

gemini-code-assist · 2025-11-05T02:07:21Z

src/content/release/breaking-changes/index.md

 [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json
 [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`]: /release/breaking-changes/flutter-root-version-file
 [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus
+[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/seperated-builder-find-child-index-callback


There's a typo in this URL path: seperated should be separated. This typo also exists in the new file's name, which will need to be corrected as well.

Suggested change

[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/seperated-builder-find-child-index-callback

[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback

gemini-code-assist · 2025-11-05T02:07:21Z

src/content/release/breaking-changes/separated-builder-find-child-index-callback.md

+    final ValueKey<String> valueKey = key as ValueKey<String>;
+    // Return item index directly - no need to multiply by 2
+    return items.indexOf(valueKey.value);


The implementation of findItemIndexCallback is incorrect. The callback should return null if the key is not found, but List.indexOf returns -1 in that case. The current implementation will return -1, which is not the expected behavior. You should check for -1 and return null instead.

Suggested change

final ValueKey<String> valueKey = key as ValueKey<String>;

// Return item index directly - no need to multiply by 2

return items.indexOf(valueKey.value);

final ValueKey<String> valueKey = key as ValueKey<String>;

final int itemIndex = items.indexOf(valueKey.value);

return itemIndex == -1 ? null : itemIndex;

gemini-code-assist · 2025-11-05T02:07:21Z

src/content/release/breaking-changes/separated-builder-find-child-index-callback.md

+    final ValueKey<String> valueKey = key as ValueKey<String>;
+    return items.indexOf(valueKey.value);


Similar to the ListView.separated example, this implementation is incorrect. It should return null when the item is not found, not -1. Please update the code to handle the not-found case correctly.

Suggested change

final ValueKey<String> valueKey = key as ValueKey<String>;

return items.indexOf(valueKey.value);

final int itemIndex = items.indexOf((key as ValueKey<String>).value);

return itemIndex == -1 ? null : itemIndex;

gemini-code-assist · 2025-11-05T02:07:22Z

src/content/release/breaking-changes/seperated-builder-find-child-index-callback.md

+
+* [`ListView.separated`][]
+* [`SliverList.separated`][]
+* [`ChildIndexGetter`][]


This list item for ChildIndexGetter will result in a broken link because its definition is missing at the end of the file. Please add the following line to the list of link definitions at the end of the file:

[`ChildIndexGetter`]: {{site.api}}/flutter/widgets/ChildIndexGetter.html

…lders

flutter-website-bot · 2025-11-05T02:12:45Z

Visit the preview URL for this PR (updated for commit 9517b90):

https://flutter-docs-prod--pr12636-seperated-builder-child-cal-zhe9wd2v.web.app

chunhtai

migration guide lgtm except for the gemini comment

sfshaza2

This lgtm, but @Piinks, can you either review or delegate review of this PR? Also, the bot has some feedback that needs to be addressed.

Piinks · 2025-11-05T21:58:25Z

can you either review or delegate review of this PR?

Looks like @chunhtai is already providing review?

sfshaza2 · 2025-11-06T17:55:59Z

@rkishan516, as @chunhtai has mentioned. Can you fix the gemini issues and then I can land.

victorsanni · 2025-11-06T23:29:13Z

src/content/release/breaking-changes/index.md

 * [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`][]
 * [Stop generating `AssetManifest.json`][]
 * [Deprecate `TextField.canRequestFocus`][]
+* [Deprecated findChildIndexCallback for separated constructors][]


Separated constructors here seems vague. It's not clear to me what API this line is referring to.

What about something like:

[Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors][]

Or is there a character limit?

…ated named constructor in ListView and SliverList (#174491) FindChildIndexCallback to take seperators into account for seperated named constructor in ListView and SliverList fixes: #174261 ## Migration guide flutter/website#12636 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.

rkishan516 · 2025-11-07T01:15:13Z

@rkishan516, as @chunhtai has mentioned. Can you fix the gemini issues and then I can land.

@sfshaza2 I have pushed all required changes.

rkishan516 requested review from a team and sfshaza2 as code owners November 5, 2025 02:05

gemini-code-assist bot reviewed Nov 5, 2025

View reviewed changes

docs: add migration guide for findChildIndexCallback of seperated bui…

9517b90

…lders

rkishan516 force-pushed the seperated-builder-child-callback branch from 994594c to 9517b90 Compare November 5, 2025 02:11

rkishan516 mentioned this pull request Nov 5, 2025

fix: findChildIndexCallback to take seperators into account for seperated named constructor in ListView and SliverList flutter/flutter#174491

Merged

9 tasks

chunhtai reviewed Nov 5, 2025

View reviewed changes

sfshaza2 changed the title ~~docs: add migration guide for findChildIndexCallback of seperated builder~~ docs: add migration guide for findChildIndexCallback of separated builder Nov 5, 2025

sfshaza2 reviewed Nov 5, 2025

View reviewed changes

docs: update findItemIndexCallback example based on gemini feedback

453c654

victorsanni reviewed Nov 6, 2025

View reviewed changes

docs: update title for migration guide

bf66530

	[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/seperated-builder-find-child-index-callback
	[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback

		final ValueKey<String> valueKey = key as ValueKey<String>;
		return items.indexOf(valueKey.value);

docs: add migration guide for findChildIndexCallback of separated builder #12636

Are you sure you want to change the base?

docs: add migration guide for findChildIndexCallback of separated builder #12636

Conversation

rkishan516 commented Nov 5, 2025

Presubmit checklist

Uh oh!

gemini-code-assist bot commented Nov 5, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

flutter-website-bot commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chunhtai left a comment

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Piinks commented Nov 5, 2025

Uh oh!

sfshaza2 commented Nov 6, 2025

Uh oh!

victorsanni Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

victorsanni Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

rkishan516 commented Nov 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

flutter-website-bot commented Nov 5, 2025 •

edited

Loading