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
