Hi Chris, these are good points, thanks for the feedback.
For java we have the ability to deprecate so we do as you mention -
major version if the API changes in non-bw compatible way. However we
haven't been enforcing that constraint for the C interface, perhaps we
should. BTW, we do list 255 in the release notes (part of the release
and also on the doc pages) as an incompatibility from 3.0.1.
I think part of the issue in 255 was that we considered this a bug more
than anything (not a feature or improvement) -- but the ABI issue you
mention still stands even if that's the case.
Btw, the version is in the config.h file, generated by autotools, as
VERSION. We don't break that out as individual parameters but we can if
there is interest.
To get this worked out and working will will take some time. If it's ok
with you, and if there is community interest in doing this, why don't we
address these process changes in 3.2? Please enter a JIRA to document
this for 3.2 and we'll work something out. We'll also do a better job of
documenting exactly what the rules are related to non-bw compat api
changes and version numbering.
Chris Darroch wrote:
I notice that 3.1.0 is on its way and it includes ZOOKEEPER-255 which
adds the Stat structure as a parameter to the zoo_set() C call. This is
a valuable change and I don't want to hold it up.
However, I thought I should point out that this kind of change
breaks the API and ABI. For major Apache C projects like the APR,
such breakage is allowed only with a major version number change:
Following such guidelines, I suppose, the old zoo_*set() functions
would remain as-is until 4.0.0, and parallel zoo_*set2() or
zoo_stat_*set() functions would add the new functionality.
Now, fair do's, ZooKeeper may not care as much as APR or httpd,
since it's mostly a Java project. At a minimum, though, it would be
excellent if there was compile-time versioning information available
so that external projects could check and, at a bare minimum, fail to
compile if the API/ABI has changed. APR has some useful guidelines
making compile-time constants (e.g., ZOO_MAJOR_VERSION) available:
Speaking personally, one really nice aspect of working with APR
for me is the parallel installation framework. Again, this might be
overkill for ZK, but I'll just point it out as well: