I generally agree. In this particular case, the distinction is clear and explained in the docs (perhaps it could be explained better, your suggestions are always welcomed).
The new names, I think, fit better: getCaretShape() are far better than getCaretShapeWithInsets (what insets? why? what makes insets so special?). The proposed solution provides the new API without breaking the existing apps. The apps can take their time to migrate to the new API in due course. I believe we've done this in the past where things got deprecated but not for removal. So I think this is a good compromise - things get fixed without immediately breaking the existing apps, a win-win. Cheers, -andy From: Michael Strauß <michaelstr...@gmail.com> Date: Monday, July 7, 2025 at 19:41 To: Andy Goryachev <andy.goryac...@oracle.com> Cc: openjfx-dev <openjfx-dev@openjdk.org> Subject: [External] : Re: Enhanced Text/TextFlow APIs 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.
