We could potentially add more annotations to cover things like public/private APIs, deprecation, etc. I lifted this initial implementation from Hadoop (thanks for the pointer Gwen!). Hadoop also has a public/private annotation that we could lift, and they use this to filter javadocs. These are useful signals, but we also don't want to make adding new code too heavyweight, so I'd prefer keeping these annotations minimal.
The immediate benefit of adding stable/unstable annotations was to make it clear a) that people should stop trying to use our in-progress APIs and b) so it's clear when we're committing in-progress code that may not be as good quality as we would normally require but is acceptable for new, in-development code that we plan to quickly iterate and improve upon before release. In the latter case, it's a useful signal internally for Kafka development that an API isn't yet fully baked even for other Kafka devs. On deprecation, I think we should definitely use the standard annotation to handle this. The annotation doesn't necessarily work for everything (e.g., deprecating older versions of the protocol doesn't work via Java deprecation annotations), but we should definitely use it for deprecated Java/Scala APIs. Perhaps we should start by marking all the old producer APIs deprecated and, after the next release, the old consumer APIs too? :) -Ewen On Wed, Aug 12, 2015 at 3:42 PM, Ismael Juma <ism...@juma.me.uk> wrote: > Hi Gwen, > > Nice to see this. There is no deprecation cycle for breakages? > > Ismael > > On Wed, Aug 12, 2015 at 11:05 PM, Gwen Shapira <g...@confluent.io> wrote: > > > Hi Team Kafka, > > > > Ewen just added stability annotations to Apache Kafka (KAFKA-2429). > > > > In the same PR, we marked the new Consumer API as "unstable" since we are > > still actively iterating on them. The goal is to mark them as "evolving" > > before the next release and after one release to validate them, we will > > mark them as "stable". > > > > When adding new public APIs, we encourage you to think of their stage of > > development and annotate correctly. > > > > The usage is: > > > > - unstable - can change at any time > > - evolving - can break compatibility at minor releases (i.e. 0.9 may be > > incompatible with 0.8) > > - stable - will only break compatibility at major releases (1.0, 2.0, > etc) > > > > Enjoy! > > > > Gwen > > > -- Thanks, Ewen
