On Wed, Apr 11, 2007 at 10:07:19AM +0100, Richard Boulton
wrote:> The policy described in that document is possibly over-conservative and
> formal, but I think it makes a good starting point for discussion.
> Comments welcomed!
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.
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 - that's saying
something deprecated
in 1.2.2 wouldn't be removed until 3.2.0, which I'm pretty sure
isn't what you
intend (and I certainly think is too conservative).
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.
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".
> In particular:
>
> - Are we happy to say that we'll keep API forward compatibility within
> a release series? I think that we should do this if at all possible: it
> shouldn't stop us adding new features within a release series in most
cases.
Yes. I think this needs to play by the same rules as not removing deprecated
methods. Otherwise we're just effectively removing functionality without
deprecating it.
> - 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.
> - Are we happy to keep deprecated features around for at least one
> whole release cycle, as described in the document? Is this longer than
> we need to? Or is this not long enough?
As ammended above, (i.e. "deprecate in 1.0.1-1.1.X, remove in 1.2.0")
I
think that's reasonable.
> I added lists to the end of the document to keep track of deprecated and
> removed features in a single place, though I've only populated the
lists
> for the C++ interface so far.
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):
/** For compatibility with Xapian 0.8.5 and earlier.
*
* @deprecated This method is now deprecated, use set_docid_order()
* instead - set_sort_forward(true) -> set_docid_order(ASCENDING)
* and set_sort_forward(false) -> set_docid_order(DESCENDING).
*/
XAPIAN_DEPRECATED(void set_sort_forward(bool sort_forward));
But once this is removed and users actually have to make such changes, all they
will have to go on is this:
0.9.0 1.0.0 Enquire::set_sort_forward() Use
Enquire::set_docid_order() instead.
This case isn't too hard to work out, but in some cases (such as
Enquire::set_sorting()) they'll probably have to download 0.9.0 and read its
documentation to know what changes to make.
> It turns out that we haven't deprecated
> any new API methods since release 0.9.0, so removing all the currently
> deprecated methods for 1.0.0 seems reasonable.
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.
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!
Cheers,
Olly