Removing deprecated functionality from a library

Say I have a method in my api called foo. In the next version of my api, I would like to replace this method with bar. How would I go about doing so?

A couple of options are:

1) Just remove foo. In the Release Notes, state that thi开发者_StackOverflow社区s method has been replaced by bar. This will break clients when they try to build using my new library, but who cares? They will just have to fix themselves.

2) Mark foo deprecated and in the Release Notes, state that bar should be preferred. Log warnings when the deprecated method is called. Then in the next version, remove foo altogether. This gives clients a small window of warning.

What would you do?

Definitely do 2.

1 above doesn't just affect compile-time, but also if your library jar is replaced by the end user, causing run-time errors.

Do 2, then 1.

During your "small window of warning" make it clear to your clients that bar is all the rage, and ensure that all (or, at your discretion, most) no longer depend on foo before removing the dead weight from your library. This way, your clients can go to the trouble at their own convenience, rather than being forced to by a binary break.

Of course, as David mentioned, you'll need to use your own judgment based on the size of your userbase. If this is a small library only used by a couple of close contacts, it may well be more effective to just make the change, but it's good form to mark as deprecated.

Your seconds choice is standard dealing with method replacement.

If the client programs are under my control, and if I have good test coverage for them, then I switch the clients to the new signature and remove the old one. Otherwise I deprecate the old signature.