My team plans to deprecate a few methods from a specific library.
I do not want to simply remove them, but dont want to return results either from the mehtods that are to be deprecated.
What are the guidelines/process I should ideally follow?
Ideally I don't think you want to sabotage the existing methods. Understand what deprecation is for:
When you deprecate a function the first time, you will piss off a bunch of your users if you completely disable it right off the bat. Their users will start complaining how the app suddenly broke and all they did was update your library for the new features. (Users don't always think these things through). So follow this process:
Apart from from the "@Deprecated" annotation, I would add to javadoc why it is beeing deprecated, alternatives to use, and define a period for keeping it that way. After that period, changing the method to throw an exception with a message saying the method "B" as been deprecated and no longer works.
Simply removing the methods or adding that exception is not a good ideia because many programs will start to fail, I usually signal them as deprecated, and just don't do any updates or bug corrections on them. Deprecated is just that, "the method won't be updated anymore"
Other projects will start to get warnings about using a deprecated method, so sooner or later, things will be corrected.
I think there is no general rule that applies to all scenarios here.
It depends a lot of who the users of the library are. The smaller the user base is and the closer the user base is to you and your team and the more chance you have to influence the applications using your library the more "aggressive" you can be in changing your public API.
When changing the client code is relatively easy you could explicitely document "this method is deprecated in version
The key here is communication - when everybody knows what happened in a release they can adapt to it.