[Xapian-devel] Deprecation Policy

[Richard Boulton]

Olly Betts wrote:
> You don't seem to consistently use the term "release series" in it.  To
> start with it talks as if 1.0.X is a release series, which seems
> reasonable to me.

That was my intention.

> But then you say:
> 
>     In general if a function is first marked as deprecated in Xapian version
>     `X.Y.c`, the function will remain present but marked as deprecated throughout
>     Xapian versions `X+1.Y.d`, and will be removed from the API at Xapian version
>     `X+2.Y.0`.  In other words, functions marked as deprecated will not be removed
>     until the end of the release series following that in which the deprecation
>     happened.
> 
> Which suggests "1.Y.Z" is a release series

Oh, that's just a typo: where it says "X+1.Y.d" it should say "X.Y+1.d". 
  Similarly where it says "X+2.Y.0"

> I suspect you mean:
> 
>     In general if a function is first marked as deprecated in Xapian version
>     `X.Y.c`, the function will remain present but marked as deprecated throughout
>     Xapian versions `X.Y.d` and `X.Y+1.e' and will be removed from the API at
>     Xapian version `X.Y+2.0`.  In other words, functions marked as deprecated
>     will not be removed until the end of the release series following that in
>     which the deprecation happened.
> 
> Except that I think deprecating in X.Y.0 should permit removal in X.Y+1.0.
> I think this might be clearer in less formal language with a couple of
> examples.

Agreed.

> I'm not sure exactly how this applies to new major releases X.0.0, but I guess
> if there is no X.Y+1.0 planned than X+1.0.0 perhaps should play the same role.
> Except then making a major sweeping change is hard, and a new major version
> number does signal "potentially incompatible changes".

I'm not sure what the resolution to this is - perhaps it's best to wait 
until we have such a sweeping change, and see how hard it is to keep 
things backward compatible in the particular case.

>>  - Are we happy to say that we'll keep ABI forward compatibility within 
>> a release series?  This is a lot more limiting, since we can't usually 
>> add features (for example, I believe that adding a method will change 
>> the layout of structures and break ABI compatibility).
> 
> I believe a new non-virtual method is OK.  Very few of our API methods are
> virtual, so that's not actually particularly limiting.

Oh good - if a new non-virtual method is OK (and I've no reason not to 
believe you), I think keeping ABI compatibility should be easy enough. 
I didn't realise it was only virtual methods which would cause a problem 
(though on reflection, that makes sense).

> As ammended above, (i.e. "deprecate in 1.0.1-1.1.X, remove in 1.2.0") I
> think that's reasonable.


> I think we should preserve the full documentation comments for removed methods
> here.  For example this tells you exactly how to update old code (and is
> currently visible in the API docs):

Good plan.  Unfortunately, tables in restructured text aren't very 
flexible - I'm running out of room.  I'll work something out, though.

> I'm unsure about removing the match bias stuff.  In many ways it's most
> deserving of removal, but leaving it there will probably help us replace it
> once ExternalPostList is merged.  We could just remove the API part I
> guess.

That might be best for 1.0.0 - otherwise, if we're going to keep the 
guarantees we're discussing here, we'll have to support it until at 
least 1.1.0.

> Not sure about documenting `#define XAPIAN_DEPRECATED(D) D' - that's just a
> hack provided so that the bindings can continue to wrap deprecated features
> without generating warnings.  I'm wary about advertising it as a supported
> feature - we're generating these warnings for a reason!

I was unsure about adding that too - I'll remove it.

-- 
Richard