[Xapian-discuss] Deprecation policy question

[Richard Boulton]

James Aylett wrote:
> I guess my only question is: why are we calling this 1.0.x not 1.1.x?

Because we're maintaining both API and ABI forwards compatibility.  ie, 
any code which works with 1.0.0 will work with 1.0.x (and will link with 
a 1.0.x library without recompilation).

> In my mind, the only thing that really gets fixed about version
> schemes is the major; minor granularity is determined by the project
> in question, and for a library the ability to compile across a minor
> version feels sensible.

In Xapian, so far, the minor version numbers have really corresponded to 
what many other projects would use as major versions; this leaves major 
version numbers somewhat less meaningful than they might otherwise be, 
but I suspect we'll probably end up using them for changes we _can't_ 
make in a compatible way (this is just my opinion, we haven't really 
discussed what makes a release major rather than minor).

ie:

  - increases of the revision part of the release number correspond to 
fixes, or to additions to the API and ABI (but not removals).  Oh, and a 
stable database format, where possible (ie, unless an important bug fix 
requires a change to the database format).
  - new minor releases correspond to API and ABI changes (ie, removal of 
features), but only following the deprecation policy; so code which 
compiled with X.Y.0 without using deprecated features will compile with 
X.Y+1.Z (for all Z), but may give deprecation warnings.
  - new major releases correspond to significant change, (and possibly 
to changes which mean that code which compiled without using deprecated 
features in the previous minor release won't compile correctly with the 
new release).

I think that restricting "revision" releases to bug-fixes only (ie, no 
new features) would mean we'd need to maintain a separate branch for new 
development, and that this could nearly double our maintainance load. 
Which is why we only make a separate branch reluctantly, as we did for 
0.9 when nearing the 1.0.0 release.

> I'm +0.5 on this concept at most though, so if others disagree that's
> fine. Either way I'm still in favour of strategy (1) for deprecation
> macros.

Sure - I'm not settled on the option I favour most, which is largely why 
I posted the question; hoping a consensus would emerge.

> Yeah, that's so minor I think it's fine to break the rules. (Can the
> macro text say precisely the simple step needed to fix things in this
> case?)

No, but we document all deprecations with suggested fixes in the header 
file (next to the macro), the release notes, and the deprecation.html 
document, so I don't think it's too much to expect for people to find 
the documentation on how to fix it.

-- 
Richard