[DO NOT MERGE] Adds page apis migration guide

[chunhtai]

waiting for flutter/flutter#137792

Presubmit checklist

• This PR doesn’t contain automatically generated corrections (Grammarly or similar).
• 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).
• This PR uses semantic line breaks of 80 characters or fewer.

[flutter-website-bot]

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

https://flutter-docs-prod--pr9873-page-apis-8eoyjmvl.web.app

[atsansone]

@chunhtai : I'll approve so you don't need to go through another round, but would recommend accepting these suggestions. Thanks!

[atsansone]

suggestion: Condition, then instruction per GSG.
Write in active voice per GSG.

Suggested change

	The developer can veto pop by returning false in the callback. This does not work well
	To veto pop, the developer can return false in the callback. This does not work well

[sfshaza2]

A global request. Rather than say "the developer", can you replace with "you"? Or reword to avoid the pronoun entirely?

[jagomf]

Simple and straight

Suggested change

	The developer can veto pop by returning false in the callback. This does not work well
	To veto pop, return `false` in the callback. This does not work well

[atsansone]

question: Is the cupertino mention an object or something else? Might be good to link to something.

[sfshaza2]

I'd change this even further:

Use the onPopPage method to clean up after a page is about to be popped.
You can veto the pop by returning false in the callback. This method doesn't work well
with other popping mechanisms in the framework,
such as [PopScope][] or CupertinoNavigationBarBackButton.

[atsansone]

suggstion: Condition, then instruction per GSG.

Suggested change

	The page APIs needed to be refactored in order to integrate them together.
	To integrate the other pop mechanisms together, the page APIs need to be refactored.

[atsansone]

suggestion: Write in active voice per GSG. Google Style doesn't recommend using a property as a noun on its own. It should modify what it's changing.

Suggested change

	The `onPopPage` is replaced by `onDidRemovePage` and no longer had the ability to veto
	a pop. In the `onDidRemovePage`, one is only responsible for updating the [`pages`].
	The `onDidRemovePage` property replaces the `onPopPage` property.
	It can no longer veto a pop.
	In the `onDidRemovePage`, one is only responsible for updating the [`pages`].

[atsansone]

suggestion: Write in active voice per GSG.

Suggested change

	The veto mechanism is moved to the `Page.canPop` and `Page.onPopInvoked` similar to how
	one uses the `PopScope` widget.
	The veto mechanism moves to the `Page.canPop` and `Page.onPopInvoked`.
	These function similar to how one uses the `PopScope` widget.

[sfshaza2]

I'd like to make further changes to this, @chunhtai. Perhaps you can make some changes, so far, and I can review it again? Definitely don't land.

[sfshaza2]

@chunhtai, this PR has become a bit of a mess. I'm closing it. Can you open a fresh copy?

thx!