With 0.x version of project at least I found lots of unexpected painful things acceptable. Graduating from 0.*, with x.y.z semantic versioning IMO it should be clearly communicated to community is there change in meaning, what's the "SLO", what are the commitments, what change in every segment means.
E.g. - APIs not labeled or labeled as stable -- change in major version is only one that can break backward compatibility (client APIs or behavior) -- change in minor version can introduce new features, but not break backward compatibility -- change in patch version, is for bug fixes only. - 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 - 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 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. 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 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. If there are changes in release cadence with new versioning, it should be clear too. Kind regards, Stevo Slavic. On Wed, Jul 19, 2017 at 1:21 AM, Ismael Juma <ism...@juma.me.uk> wrote: > With regards to the annotations, I think we should expect that we'll always > have some @Evolving APIs. Even though much of the platform is mature, we'll > continue to improve and extend it. I'm generally not a fan of @Unstable > (since there's rarely a reason to make breaking changes in bug fix release) > and I would not mind if we removed them from the codebase for good. > > Ismael > > On Tue, Jul 18, 2017 at 4:07 PM, Guozhang Wang <wangg...@gmail.com> wrote: > > > Currently the only @unstable annotations left are on Streams and one > class > > of Security modules, and I think we have a good chance of removing them > all > > in the next release. > > > > We also have a few @evolving annotations on the Admin, Streams, Security > > modules etc. And I think we can try to also eliminate as many of them as > > possible if people feel confident about these APIs but maybe a stretch > goal > > to get rid of all of them. > > > > Guozhang > > > > On Tue, Jul 18, 2017 at 3:49 PM, Gwen Shapira <g...@confluent.io> wrote: > > > > > Also fine with the change in general. > > > > > > As you mentioned, 1.x indicates mature APIs, compatibility and > stability. > > > Are we going to remove the @unstable annotations in this release? > > > > > > Gwen > > > > > > On Tue, Jul 18, 2017 at 3:43 PM Ismael Juma <ism...@juma.me.uk> wrote: > > > > > > > Hi Guozhang, > > > > > > > > Thanks for volunteering to be the release manager for the next > release! > > > > > > > > I am +1 on naming the next release 1.0.0. As you said, Kafka is > mature > > > > enough and this will make it easier for others to understand our > > > versioning > > > > policy. > > > > > > > > A couple of minor questions inline. > > > > > > > > On Tue, Jul 18, 2017 at 3:36 PM, Guozhang Wang <wangg...@gmail.com> > > > wrote: > > > > > > > > > major.minor.bugfix[.release-candidate] > > > > > > > > > > > > > I think you mean major.minor.bugfix-rc (i.e. we typically use a dash > > > > instead of dot for the RCx qualifier). > > > > > > > > > > > > > > How do people feel about 1.0.0.x as the next Kafka version? > > > > > > > > > > > > Do you mean 1.0.0? > > > > > > > > Ismael > > > > > > > > > > > > > > > -- > > -- Guozhang > > >
