Deprecation is a really good solution for fixing things "eventually" but only if you pair it with a plan for making the old one go away forever (a plan that you

Deprecation is a really good solution for fixing things "eventually" but only if you pair it with a plan for making the old one go away forever (a plan that you stick to!). If you aren't serious about actually removing a bad API at some point, don't change anything. Otherwise, you create two things that need to be tested/supported/kept binary-compatible/etc. instead of one, raising technical debt when you were supposed to lower it.