+1 on 1.0. It's about time :) On Thu, Jul 20, 2017 at 5:11 PM Ewen Cheslack-Postava <e...@confluent.io> wrote:
> Ack on the deprecation, as long as we actually give people the window. I > guess we're not doing a good job of communicating what that period is > anyway, so we can play a bit fast and loose. > > -Ewen > > On Thu, Jul 20, 2017 at 4:59 PM, Guozhang Wang <wangg...@gmail.com> wrote: > > > We do have the KIP in the candidate list of the next release (see wiki > > https://cwiki.apache.org/confluence/display/KAFKA/Release+Plan+2017.Oct) > > as KIP-118: > > Drop Support for Java 7 in Kafka 0.11 > > <https://cwiki.apache.org/confluence/display/KAFKA/KIP- > > 118%3A+Drop+Support+for+Java+7+in+Kafka+0.11> > > . > > > > Guozhang > > > > 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 > > > -- Thanks, Neha
