(Un-)Deprecated APIs and javadoc examples

[Steven Willis <sw...@compete.com>]

(I just finished writing this when I noticed the similar email from Marcos bringing up similar issues with the Yahoo tutorials)

I've read through the following:

http://www.mail-archive.com/mapreduce-dev@hadoop.apache.org/msg01833.html
http://www.mail-archive.com/general@hadoop.apache.org/msg04621.html
https://issues.apache.org/jira/browse/MAPREDUCE-1734
https://issues.apache.org/jira/browse/MAPREDUCE-1735
https://issues.apache.org/jira/browse/MAPREDUCE-3771

And it looks like every branch has un-deprecated the old APIs (except for 0.22?). But it seems like from the first discussion above, several people who were okay with un-deprecating the old APIs thought they would still be re-deprecated (and even removed) prior to a 1.0 release, which has obviously not happened. Is re-deprecating the old APIs on the horizon at all for any of the branches?

I started writing mapreduce code using the old APIs because the vast majority of examples and tutorials used the old APIs. But when I started encountering the deprecated warnings and I found the new APIs, I started porting my code. I felt like the warnings were a good indication of where I should be heading with the code. And having: "Deprecated. Use XyzClass instead" was very helpful. Now, with these classes being un-deprecated, users have no clue what they should/should not be using. This issue is compounded when examples in the API docs use these once-deprecated classes. For example: the use of JobConf in an example from:

http://hadoop.apache.org/common/docs/r0.23.0/api/org/apache/hadoop/util/Tool.html

Without either deprecated warnings or good examples using the new API, new hadoop developers will continue to use the old APIs. If these classes aren't going to be re-deprecated any time soon, shouldn't at least the javadoc examples be updated to use only the new APIs so that developers have some indication of where they should be going with their code?

-Steven Willis

RE: (Un-)Deprecated APIs and javadoc examples

[Steven Willis <sw...@compete.com>]

> 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

Re: (Un-)Deprecated APIs and javadoc examples

[Harsh J <ha...@cloudera.com>]

Hi Steve,

With 0.23 (or 2.0, going forward), it is alright to use either set.
You can also continue using the new API - it is fairly complete in 2.0
and usable (compared to 1.x).

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. The latter is unstable
cause it can change furthermore in some internal parts, and may have
also have some minor bugs in it (I recall one about output committers
being set for instance, but the JIRA ID fails me right now).

What would you suggest for resolving this long running pain?

On Thu, Apr 5, 2012 at 3:30 AM, Steven Willis <sw...@compete.com> wrote:
> (I just finished writing this when I noticed the similar email from Marcos bringing up similar issues with the Yahoo tutorials)
>
> I've read through the following:
>
> http://www.mail-archive.com/mapreduce-dev@hadoop.apache.org/msg01833.html
> http://www.mail-archive.com/general@hadoop.apache.org/msg04621.html
> https://issues.apache.org/jira/browse/MAPREDUCE-1734
> https://issues.apache.org/jira/browse/MAPREDUCE-1735
> https://issues.apache.org/jira/browse/MAPREDUCE-3771
>
> And it looks like every branch has un-deprecated the old APIs (except for 0.22?). But it seems like from the first discussion above, several people who were okay with un-deprecating the old APIs thought they would still be re-deprecated (and even removed) prior to a 1.0 release, which has obviously not happened. Is re-deprecating the old APIs on the horizon at all for any of the branches?
>
> I started writing mapreduce code using the old APIs because the vast majority of examples and tutorials used the old APIs. But when I started encountering the deprecated warnings and I found the new APIs, I started porting my code. I felt like the warnings were a good indication of where I should be heading with the code. And having: "Deprecated. Use XyzClass instead" was very helpful. Now, with these classes being un-deprecated, users have no clue what they should/should not be using. This issue is compounded when examples in the API docs use these once-deprecated classes. For example: the use of JobConf in an example from:
>
> http://hadoop.apache.org/common/docs/r0.23.0/api/org/apache/hadoop/util/Tool.html
>
> Without either deprecated warnings or good examples using the new API, new hadoop developers will continue to use the old APIs. If these classes aren't going to be re-deprecated any time soon, shouldn't at least the javadoc examples be updated to use only the new APIs so that developers have some indication of where they should be going with their code?
>
> -Steven Willis



-- 
Harsh J