Thanks for trying to land this with as little breakage as possible. I'm guessing having it default to onScrollUpdate is because of this comment? Although since the goal is to match native we might have to just break directly. I'm not really sure how to proceed, @MitchellGoodwin what do you think?

Haven't seen that comment, actually.

My hunch is that, even though the current behaviour is a "bug", some folks might have had some logic built around it, so I didn't want to outright break it.

It's your call, I'm fine with any decision.

In my opinion, have it default to the non-breaking behavior, and call out that the default behavior is the other enum option in the documentation. When this reaches stable, we can recommend setting the enum to the right value to get native behavior, then if we change the default after that we'll have given warning, and we can possibly do a dart fix. Changing the functional behavior suddenly is a little dangerous, and easy to miss in communications.

Since it is a new optional parameter, I am not sure that folks will notice a change in the documentation that doesn't force them to do something to acknowledge the new behaviour.

They might miss it, yes. But we can highlight it in the release blog and breaking change guides before it's made default to create some resources. Mentioning it in the docs is more for helping with a migration and future understanding, rather than informing the developers that a breaking change is happening.