I am working on a common API for a user interface. My colleagues use this framework in all their projects, but the UI is not our main aspect here, so the knowledge of the UI framework is somewhat limited to example code and past experience.
This framework has a function addSCW, which probably means add some custom widget. Now, I have extended this Custom Widget by a few adaptations for a specific application. The behavior of the new widget is not consistent with the old widget in some aspects, but in 80% of use cases it behaves exactly the same as the old one. I want to make my update available to other users by adding a new callback to the API. At the same time, I need to make sure the API is backwards compatible.
Function addSCW must stay. I could add a new function: addSCW2, or addSomeCustomWidget, or addSomeNewCustomWidget, or addSNCW, or whatever else. I am overwhelmed by the freedom of being allowed to name a new API function.
- I need to make sure that users are aware that they can use either
addSCWfor the old interface, oraddSNCWfor the new interface, - I want to make it is easy to replace the old function with the new function,
- I would like the function name to expose what the returned object is, but this is already achieved by the existing callback,
- new function returns in fact an extended version of what the old function returned,
- I hate to call API functions
addSCW2, because then there would beaddSCW3andaddSCW4, none of which really explains what is the difference between them all.
Is there any best practice on how to modify an API by adding a new callback which is very similar to an existing callback? How can I inform the users that a new feature should be used in new projects?
