[Xapian-devel] Deprecation Policy
Richard Boulton
richard at lemurconsulting.com
Wed Apr 11 13:56:45 BST 2007
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
More information about the Xapian-devel
mailing list