In most cases, I would advise against having similarly-named methods that exhibit different semantics. If the behavior of the existing methods is indeed a bug (and not just different, but legitimate semantics), then fixing that would be best. We've done breaking changes in the past where appropriate, and expect applications to make necessary changes in their API use when switching to a new version of JavaFX. Always keeping old behavior around runs the risk of fossilizing the API in the long run.
In rare cases, and especially when necessary changes would be more involved, there's the option to hide the previous behavior behind a system property. Setting a system property in lieu of changing code is a low-effort option for applications that are not prepared to fix their code just yet. If we want to keep the old methods around indefinitely, another option would be to make the new methods clearly different to indicate their changed semantics. For example, for the existing method `rangeShape(int, int)`, we could add another method `rangeShapeWithLineSpacing(int, int)`. This makes the semantics of the method abundantly clear to users, and keeps the old method around. It also avoids the proposed boolean argument `includeLineSpacing`, which is usually better API design. As another example, the existing method `caretShape(int, boolean)` could be paired with `caretShapeWithInsets(int, boolean)`. My main criticism is that method pairings like `rangeShape` and `getRangeShape` muddy the API waters. We'd never have done that, had we thought about the correct semantics earlier. Evolving an API is always hard, but the goal should be to have the new API fit well with the existing API, as if it had been thought of from the beginning.
