Sönke Liebau commented on KAFKA-5637:

My personal expectation for a stable, public API would be that it is binary as 
well as source compatible i.e. no changes at all to anything public facing.

Verifying this is probably not an easy task, there are tools out there that 
analyse compatibility at both levels, however embedding these in the build 
process and getting it to recognize our stability annotations as well as the 
rules in relation to version changes seems like a quite daunting task to me 
tbh. I suspect that this is something we need to catch when reviewing changes 
(can be tool assisted for larger changes - but as a manual run).  
Additionally we could add a manual step to the release process to generate a 
compatibility report against previous versions and evaluate this against stable 
APIs and the specific rules in effect for the version change.

As for different rules for unstable APIs, I'd say that we stick to one 
definition of "compatible" across all levels of stability.

> Document compatibility and release policies
> -------------------------------------------
>                 Key: KAFKA-5637
>                 URL: https://issues.apache.org/jira/browse/KAFKA-5637
>             Project: Kafka
>          Issue Type: Improvement
>          Components: documentation
>            Reporter: Ismael Juma
>            Assignee: Sönke Liebau
>             Fix For: 1.0.0
> We should document our compatibility and release policies in one place so 
> that people have the correct expectations. This is generally important, but 
> more so now that we are releasing 1.0.0.
> I extracted the following topics from the mailing list thread as the ones 
> that should be documented as a minimum: 
> *Code stability*
> * Explanation of stability annotations and their implications
> * Explanation of what public apis are
> * *Discussion point: * Do we want to keep the _unstable_ annotation or is 
> _evolving_ sufficient going forward?
> *Support duration*
> * How long are versions supported?
> * How far are bugfixes backported?
> * How far are security fixes backported?
> * How long are protocol versions supported by subsequent code versions?
> * How long are older clients supported?
> * How long are older brokers supported?
> I will create an initial pull request to add a section to the documentation 
> as basis for further discussion.

This message was sent by Atlassian JIRA

Reply via email to