This is definitely an area we can improve upon, thanks for bringing it up Gwen. We should also decide on structure for how we publish too that has not been something I have been consistent about for each release that should be standard.
We can publish to SVN but I always feel like drift happens there. In 0.8.2-beta I pushed them so they are in dist now https://archive.apache.org/dist/kafka/0.8.2-beta/ as java-doc and scala-doc maybe that is ok for final? The content should be as helpful as it can be to folks, for sure. Gwen, do you want to create a JIRA and work on a patch for this? I feel like it is something important for 0.8.2 that wouldn't impact code (and if it does it is for good reason to best stabilize) not sure what other folks think of that though? 0.8.3 for sure +1 /******************************************* Joe Stein Founder, Principal Consultant Big Data Open Source Security LLC http://www.stealth.ly Twitter: @allthingshadoop <http://www.twitter.com/allthingshadoop> ********************************************/ On Tue, Dec 16, 2014 at 1:04 PM, Gwen Shapira <gshap...@cloudera.com> wrote: > > Hi, > > Kafka has public APIs in Java and Scala, intended for use by external > developers. > In addition, Kafka also exposes many public methods that are intended > to use within Kafka but are not intended to be called by external > developers. > Also, some of the external APIs are less stable than others (the new > producer for example). > > In Hadoop we have a similar situation, and to avoid misunderstandings > or miscommunications on which APIs are external and which are stable, > we use annotations to communicate this information. > We find it very useful in preventing our customers from accidentally > getting into trouble by using internal methods or unstable APIs. > > Here are the annotations Hadoop uses: > > https://hadoop.apache.org/docs/current/api/src-html/org/apache/hadoop/classification/InterfaceStability.html > > https://hadoop.apache.org/docs/current/api/src-html/org/apache/hadoop/classification/InterfaceAudience.html > > I'm wondering what others think about using something similar in Kafka. > > Gwen >
