> There is still some shadows on API deprecation however. We do want to > support both APIs for a longer term, per our earlier discussions on > this list. However, this is a developer nightmare again cause docs > would go inconsistent and questions would arise on what to pick. > > We'd have to pick between deprecating one of the APIs to solve > developer nightmare (and fixing/cleaning docs to reflect our movement), > or we need to have strong messaging in dev docs saying both API is good > to use, but the stable API is what you should choose unless you favor a > feature in unstable API.
I had probably misinterpreted the aim then. I thought if a developer were writing brand new code and didn't have anything tying them to the old APIs, then they should use the new API. Basically, if what you need is a subset of the old and the new, then go with new. > What would you suggest for resolving this long running pain? Personally, I never minded the deprecated warnings. I figured I could write mostly against the new API, and the few places I absolutely needed a deprecated class, I could deal with the warnings or simply suppress them while I waited for the new API to catch up. My suggestion would be to put as much emphasis on the new API as possible, any/all examples (especially those in the javadocs) should be updated to use the new API exclusively. Where they can't, a note should be made that says something like, "The use of this old class/interface is currently necessary, but should be replaced with xyz in the future." Any examples in the old classes' javadocs wouldn't need updating of course, but a note should be made to look over at the new classes. If deprecated warnings are considered overkill, then perhaps just comments in the javadoc stating that a class is deprecated (or maybe something softer). -Steve
