The correct way should be the default, but in the case where you already chose the wrong default, you shouldn't introduce the correct way of handling things and

The correct way should be the default, but in the case where you already chose the wrong default, you shouldn't introduce the correct way of handling things and make it the default all at once. Upgrading to a new major version should never require changes to your code if you fixed all deprecation warnings in the previous major version. Otherwise, you make incremental upgrades impossible. The new alternative should always be introduced as opt-in with the old default deprecated, and then made default in the next major version.