That's a good question, from https://cwiki.apache.org/confluence/display/KAFKA/Release+Plan+0.11.0.0 it seems we do have one deprecation (KIP-109: Old Consumer Deprecation <https://cwiki.apache.org/confluence/display/KAFKA/KIP-109%3A+Old+Consumer+Deprecation>). I'm fine with not removing the deprecated old consumer in the next release even if it is bumped up as a major.
Guozhang On Thu, Jul 20, 2017 at 4:44 PM, Ewen Cheslack-Postava <e...@confluent.io> wrote: > Did we deprecate anything in 0.11.0? The one concern with bumping major > versions in consecutive releases is that you may not give people the room > for transition if you deprecate and then immediately remove in the next > release. > > -Ewen > > On Thu, Jul 20, 2017 at 4:51 AM, Damian Guy <damian....@gmail.com> wrote: > > > +1 on 1.0! > > Are we also going to move to java 8? > > I also think we should drop the Unstable annotations completely. > > > > Cheers, > > Damian > > > > On Wed, 19 Jul 2017 at 21:36 Guozhang Wang <wangg...@gmail.com> wrote: > > > > > Hi Stevo, > > > > > > Just trying to add to what Ismael has already replied you: > > > > > > > > > > Practice/"features" like protocol version being a parameter, and > > > defaulting > > > > to latest so auto updated with dependency update which introduces new > > > > protocol/behavior should not be used in public client APIs. To switch > > > > between backward incompatible APIs (contract and behaviors), ideally > > user > > > > should explicitly have to change code and not dependency only, but at > > > least > > > > it should be clearly communicated that there are breaking changes to > > > expect > > > > even with just dependency update by e.g. giving major version release > > > clear > > > > meaning. If app dependency on Kafka client library minor.patch on > same > > > > major is updated, and if there's a change in behavior or API > requiring > > > app > > > > code change - it's a bug. > > > > > > > > Change introduced contrary to the SLO, is OK to be reported as bug. > > > > Everything else is improvement or feature request. > > > > > > > > If this was the case, and 1.0.0 was released today with APIs as they > > are > > > > now, Scala client APIs even though deprecated would not break and > > require > > > > refactoring with every 1.* minor/patch release, and would only be > > allowed > > > > to be broken or removed in future major release, like 2.0.0 > > > > > > Just to clarify, my proposal is that moving forward beyond the next > > release > > > we will not make any public API breaking changes in any of the major or > > > minor releases, but will only mark them as "deprecated", and deprecated > > > public APIs will be only considered for removing as early as the next > > major > > > release: so if we mark the scala consumer APIs as deprecated in 1.0.0, > we > > > should only be consider removing it at 2.0.0 or even later. > > > > > > > It should be also clear how long is each version supported - e.g. if > > > > minor.patch had meaning that there are no backward incompatible > > changes, > > > > it's OK to file a bug only for current major.minor.patch; previous > > major > > > > and its last minor.patch can only have patches released up to some > time > > > > like 1 up to 3 months. > > > > > > Currently in practice we have not ever done, for example a bugfix > release > > > on an older major / minor release: i.e. once we have released say > > 0.10.2.0 > > > we did not release 0.10.1.2 any more. So practically speaking we do not > > > have a "support period" for older versions yet, and in the next coming > > > release I do not have plans to propose some concrete policy for that > > > matter. > > > > > > > > > Guozhang > > > > > > > > > > > > On Wed, Jul 19, 2017 at 2:12 AM, Ismael Juma <ism...@juma.me.uk> > wrote: > > > > > > > Hi Stevo, > > > > > > > > Thanks for your feedback. We should definitely do a better job of > > > > documenting things. We basically follow semantic versioning, but it's > > > > currently a bit confusing because: > > > > > > > > 1. There are 4 segments in the version. The "0." part should be > ignored > > > > when deciding what is major, minor and patch at the moment, but many > > > people > > > > don't know this. Once we move to 1.0.0, that problem goes away. > > > > > > > > 2. To know what is a public API, you must check the Javadoc ( > > > > https://kafka.apache.org/0110/javadoc/index.html?org/apache/ > > > > kafka/clients/consumer/KafkaConsumer.html). > > > > If it's not listed there, it's not public API. Ideally, it would be > > > obvious > > > > from the package name (i.e. there would be "internals" in the name), > > but > > > we > > > > are not there yet. The exception are the old Scala APIs, but they > have > > > all > > > > been deprecated and they will be removed eventually (the old Scala > > > > consumers won't be removed until the June 2018 release at the > earliest > > in > > > > order to give people time to migrate). > > > > > > > > 3. Even though we are following reasonably common practices, we > haven't > > > > documented them all in one place. It would be great to do it during > the > > > > next release cycle. > > > > > > > > A few comments below. > > > > > > > > On Wed, Jul 19, 2017 at 1:31 AM, Stevo Slavić <ssla...@gmail.com> > > wrote: > > > > > > > > > - APIs not labeled or labeled as stable > > > > > -- change in major version is only one that can break backward > > > > > compatibility (client APIs or behavior) > > > > > > > > > > > > > To clarify, stable APIs should not be changed in an incompatible way > > > > without a deprecation cycle. Independently of whether it's a major > > > release > > > > or not. > > > > > > > > > > > > > -- change in minor version can introduce new features, but not > break > > > > > backward compatibility > > > > > -- change in patch version, is for bug fixes only. > > > > > > > > > > > > > Right, this has been the case for a while already. Also see > annotations > > > > below. > > > > > > > > > > > > > - APIs labeled as evolving can be broken in backward incompatible > way > > > in > > > > > any release, but are assumed less likely to be broken compared to > > > > unstable > > > > > APIs > > > > > - APIs labeled as unstable can be broken in backward incompatible > way > > > in > > > > > any release, major, minor or patch > > > > > > > > > > > > > The relevant annotations do explain this: > > > > > > > > > > > https://kafka.apache.org/0110/javadoc/org/apache/kafka/ > > common/annotation/ > > > > InterfaceStability.html > > > > > > > https://kafka.apache.org/0110/javadoc/org/apache/kafka/ > > common/annotation/ > > > > InterfaceStability.Stable.html > > > > > > > https://kafka.apache.org/0110/javadoc/org/apache/kafka/ > > common/annotation/ > > > > InterfaceStability.Evolving.html > > > > > > > https://kafka.apache.org/0110/javadoc/org/apache/kafka/ > > common/annotation/ > > > > InterfaceStability.Unstable.html > > > > > > > > But we should have a section in our documentation as well. > > > > > > > > > > > > > - deprecated stable APIs are treated as any stable APIs, they can > be > > > > > removed only in major release, are not allowed to be changed in > > > backward > > > > > incompatible way in either patch or minor version release > > > > > > > > > > > > > Right, but note that stable non-deprecated APIs provide stronger > > > guarantees > > > > in major releases (they can't be changed in an incompatible way). > > > > > > > > > > > > > > This means one should be able to upgrade server and > recompile/deploy > > > apps > > > > > with clients to new minor.patch release with dependency version > > change > > > > > being only change needed and there would be no drama. > > > > > > > > > > > > > That should have been the case for a while as long as you are using > > > stable > > > > public APIs. > > > > > > > > > > > > > > Practice/"features" like protocol version being a parameter, and > > > > defaulting > > > > > to latest so auto updated with dependency update which introduces > new > > > > > protocol/behavior should not be used in public client APIs. To > switch > > > > > between backward incompatible APIs (contract and behaviors), > ideally > > > user > > > > > should explicitly have to change code and not dependency only, but > at > > > > least > > > > > it should be clearly communicated that there are breaking changes > to > > > > expect > > > > > even with just dependency update by e.g. giving major version > release > > > > clear > > > > > meaning. If app dependency on Kafka client library minor.patch on > > same > > > > > major is updated, and if there's a change in behavior or API > > requiring > > > > app > > > > > code change - it's a bug. > > > > > > > > > > > > > Hmm, if the protocol bump provides improved behaviour, that is not a > > > > backwards incompatible change though. So, I don't think I agree with > > > this. > > > > Of course, > > > > it does mean that _downgrading_ may cause loss of functionality. > That's > > > OK, > > > > in my opinion. > > > > > > > > Change introduced contrary to the SLO, is OK to be reported as bug. > > > > > Everything else is improvement or feature request. > > > > > > > > > > If this was the case, and 1.0.0 was released today with APIs as > they > > > are > > > > > now, Scala client APIs even though deprecated would not break and > > > require > > > > > refactoring with every 1.* minor/patch release, and would only be > > > allowed > > > > > to be broken or removed in future major release, like 2.0.0 > > > > > > > > > > > > > Yes, that is the plan for any _public_ Scala client APIs that are > still > > > > present in 1.0.0. The public Scala client APIs are the producer and > > > > consumer, basically. Again, we should make this clear in our > > > documentation. > > > > Note that we have made an effort to keep those APIs compatible for > > quite > > > a > > > > while. It sounds like you have had some issues, were they related to > > > usage > > > > of internal Admin APIs by any chance (since we didn't have a public > > > > AdminClient API until very recently)? > > > > > > > > > > > > > > It should be also clear how long is each version supported - e.g. > if > > > > > minor.patch had meaning that there are no backward incompatible > > > changes, > > > > > it's OK to file a bug only for current major.minor.patch; previous > > > major > > > > > and its last minor.patch can only have patches released up to some > > time > > > > > like 1 up to 3 months. > > > > > > > > > > > > > I am not sure I understood this point correctly. Can you please > > clarify? > > > > > > > > If there are changes in release cadence with new versioning, it > should > > be > > > > > clear too. > > > > > > > > > > > > > No changes are planned. We have started time-based releases less > than a > > > > year ago and they seem to be going well. > > > > > > > > Ismael > > > > > > > > > > > > > > > > -- > > > -- Guozhang > > > > > > -- -- Guozhang
