Adds migration guide for default cache extent change

[chunhtai]

for flutter/flutter#182905

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.

[flutter-website-bot]

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

https://flutter-docs-prod--pr13177-cache-default-th9gvcrr.web.app

[sfshaza2]

I know that this is still in draft form, but lgtm, so it's ready when you are.

[chunhtai]

update: still migrating internal tests and the pr is under code freeze

[gemini-code-assist]

Code Review

This pull request introduces documentation for a breaking change where the default cacheExtent for scrolling widgets is updated from a fixed 250 pixels to 0.8 times the viewport size. The review feedback focuses on ensuring the documentation adheres to the project's style guide by implementing semantic line breaks and maintaining a maximum line length of 80 characters. Additionally, there is a suggestion to explicitly include ScrollView in the list of affected widgets.

[gemini-code-assist]

This line exceeds 80 characters and does not use semantic line breaks as required by the project's style guide. Additionally, consider adding ScrollView to the list of widgets, as it is the base class that defines the property.

Suggested change

	The default cache extent for scrolling widgets (`ListView`, `GridView`, `CustomScrollView`, and `Scrollable`) changed from a fixed value of `250.0` pixels to `0.8` times the viewport's dimension along the main axis.
	The default cache extent for scrolling widgets
	(`ScrollView`, `ListView`, `GridView`, `CustomScrollView`, and `Scrollable`)
	changed from a fixed value of `250.0` pixels
	to `0.8` times the viewport's dimension along the main axis.

References

1. The project requires semantic line breaks of 80 characters or fewer for documentation. ^(link)

[gemini-code-assist]

These lines exceed 80 characters and should use semantic line breaks to improve readability and diffing, as specified in the PR checklist.

Suggested change

	Previously, the default cache extent was `250.0` pixels. A fixed pixel cache extent is too small on large monitors and unnecessarily large on very small screens. Furthermore, the fixed 250-pixel cache extent can be too small to accommodate accessibility scrolling, which is based on the viewport size. This sometimes causes iOS VoiceOver to lose its current focus because the currently focused item scrolls outside of the cache extent.
	The new default cache extent is `0.8` times the viewport extent. The cache region extends 80% of the viewport's main axis dimension both before and after the visible area. This preloads an appropriate amount of content for any screen size.
	Previously, the default cache extent was `250.0` pixels.
	A fixed pixel cache extent is too small on large monitors
	and unnecessarily large on very small screens.
	Furthermore, the fixed 250-pixel cache extent can be too small
	to accommodate accessibility scrolling, which is based on the viewport size.
	This sometimes causes iOS VoiceOver to lose its current focus
	because the currently focused item scrolls outside of the cache extent.
	The new default cache extent is `0.8` times the viewport extent.
	The cache region extends 80% of the viewport's main axis dimension
	both before and after the visible area.
	This preloads an appropriate amount of content for any screen size.

References

1. The project requires semantic line breaks of 80 characters or fewer for documentation. ^(link)

[gemini-code-assist]

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change

	Any scrolling widget that relies on the default cache extent will now have a cache extent relative to its viewport size instead of a fixed `250.0` pixels.
	Any scrolling widget that relies on the default cache extent
	will now have a cache extent relative to its viewport size
	instead of a fixed `250.0` pixels.

References

1. The project requires semantic line breaks of 80 characters or fewer for documentation. ^(link)

[gemini-code-assist]

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change

	* New behavior: The cache area is `1000 * 0.8 = 800` pixels above and below the visible area.
	* New behavior: The cache area is `1000 * 0.8 = 800` pixels
	above and below the visible area.

References

1. The project requires semantic line breaks of 80 characters or fewer for documentation. ^(link)

[gemini-code-assist]

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change

	This change does not affect widgets where the cache extent is explicitly provided (such as `ListView(cacheExtent: 500)` or `ListView(scrollCacheExtent: ScrollCacheExtent.pixels(500))`).
	This change does not affect widgets where the cache extent is explicitly
	provided (such as `ListView(cacheExtent: 500)` or
	`ListView(scrollCacheExtent: ScrollCacheExtent.pixels(500))`).

References

1. The project requires semantic line breaks of 80 characters or fewer for documentation. ^(link)

[gemini-code-assist]

This line exceeds 80 characters. Please use semantic line breaks.

Suggested change

	Most applications do not require modifications. If your application relies on the 250-pixel default, you can restore the previous behavior by explicitly setting the cache extent property.
	Most applications do not require modifications.
	If your application relies on the 250-pixel default,
	you can restore the previous behavior by explicitly setting
	the cache extent property.

References

1. The project requires semantic line breaks of 80 characters or fewer for documentation. ^(link)