It sounds like this is saying that the thing you should do now is something that will stop working in the future. Am I understanding it correctly?

Is there planned to be a point in the future where the new way has started working, but this interim way is still working and hasn't yet been removed? I think it would be quite helpful to make that be the case, so that people can go step by step through

1. upgrade Flutter to version N;
2. update their code to the new way;
3. upgrade Flutter to version M > N;

and have a working app at each step.

As is, it sounds like perhaps the new way to handle this use case will only begin to work correctly at the same time as the interim way gets removed, which will make upgrades more challenging.

Ah good point, I didn't fully think this through when I planned this deprecation. I probably should have fully deprecated TextSelectionControls and replaced it with TextSelectionHandleControls. But given that I didn't...

Option 1: Immediate breaking change (current)

Remove the methods from TextSelectionControls and remove TextSelectionHandleControls at the same time.

Affected people (those using both contextMenuBuilder and TextSelectionControls) will have to migrate to TextSelectionHandleControls, then face an immediate breaking change when it is removed and have to migrate back to TextSelectionControls.

Option 2: Two stage deprecation

Remove the methods from TextSelectionControls first. At this point, TextSelectionControls and TextSelectionHandleControls are identical but TextSelectionHandleControls is deprecated. In the second stage, remove TextSelectionHandleControls.

Affected people will migrate to TextSelectionHandleControls, then get a warning that it is deprecated and migrate back to TextSelectionControls.

Option 3: More breaking changes

I could potentially try to jump back on the path I should have taken from the start, by un-deprecating TextSelectionHandleControls and deprecating TextSelectionControls.

A slight negative of this plan is for people who were only using TextSelectionControls for building handles and didn't care about toolbars. They would never be affected by the previous two options, but they would have to migrate to TextSelectionHandleControls under this third option.

For the record, why did I do this in the first place?

I needed a way to distinguish between the old path (TextSelectionControls.buildToolbar) and new path (contextMenuBuilder) because during the deprecation period, both need to work simultaneously. The way I could determine which to use is if selectionControls is TextSelectionHandleControls, then they definitely want to use the new post-deprecation path. Otherwise I would continue to use buildToolbar during the deprecation period.

@Piinks Do you have any thoughts on this deprecation conundrum? 🌪️

Happy to help! In general, if we want folks to ultimately migrate from API A to C, we should make that path available to them in as easy a transition as possible. If there is a migration from A to B to C, this is a lot of churn on developers.

This class was created as a stopgap during the deprecation period.

Usually we try to avoid this, will this work after the deprecation period and also be deprecated for a while, maintaining backwards compatibility? Otherwise, it looks like it may just be a hard break that has been kicked down the road for the future.

Is there currently a migration path that exists as a final destination for developers? As in, can a developer migrate from the currently deprecated API A to the final API C that they should be using going forward? If so, we should deprecate this temp class now so folks can move gracefully. Any other associated deprecations can be updated to extend the deprecation period.

If the final destination path to C is not available yet, here is an option we could take.. when the final destination C is available, deprecate this temp class and update the current deprecations to extend the period. That way folks can easily transition to the end goal API C when it is ready. It seems pretty easy all around for everyone since it won't require rolling anything back or making a hard break, just a little more time to allow folks to migrate.

However, I don't have 100% context here. Should EditableText.contextMenuBuilder be deprecated? Is that the API that folks should not be using? What is the A B C of this equation? :)

Thanks for your thoughts! For the purpose of ultimately migrating from TextSelectionControls.buildToolbar to EditableText.contextMenuBuilder, your equation would be:

• A: TextSelectionControls.buildToolbar and TextSelectionControls.buildHandle
• B: EditableText.contextMenuBuilder and TextSelectionHandleControls.buildHandle
• C: EditableText.contextMenuBuilder and TextSelectionControls.buildHandle

There is no final destination path from A to C right now. It's not possible for developers to migrate to C until TextSelectionHandleControls has been deleted.

If I don't want all of the deprecations to be removed at the same time, then can I just update the "This feature was deprecated after vx.x.x" string? Looks like it currently says v3.3.0-0.5.pre, but the latest is 3.9.0-21.0.pre. If so I should probably do that immediately, before the release.

I would consider option 3, which would make this just an A=>B kind of migration, but it would require nontrivial changes that I don't want to try to get into the release right now.

I've opened a PR to do this if I understand correctly (Option 2). #124262

Should this perhaps be mentioned on [EditableText.contextMenuBuilder] and/or on [buildHandle]?