[Xapian-discuss] Deprecation policy question

[Olly Betts]

On Mon, Sep 24, 2007 at 09:05:36AM +0100, Richard Boulton wrote:
> 4. A macro is used to mark features as deprecated, so that compilers 
> will emit a warning when the deprecated feature is used.

It's perhaps worth mentioning that this macro requires explicit support
from the compiler - currently it works for GCC 3.1 or later, and
MSVC 7.0 or later (which I suspect is the majority of users).  If
you know how to do this for another compiler, do let us know.

> 1. Always add the deprecation macro as soon as the feature is deprecated 
> (so, at version 1.0.3 in the above example).  This is good because users 
> get as much warning as possible about changes they will need to make to 
> their code, but bad because it will sometimes mean that it is not 
> possible to write code which compiles without warnings with all 
> revisions of xapian within a release series.

It's always possible to write code using the preprocessor, like this:

#if XAPIAN_MAJOR_VERSION == 1 && XAPIAN_MINOR_VERSION < 3
    old_way();
#else
    new_way();
#endif

This approach could get ugly for some cases, though probably not for the
sort of changes we're likely to be happy to include in a point release.

It's also worth noting that you can easily disable all Xapian
deprecation warnings like the bindings do:

#define XAPIAN_DEPRECATED(D) D

That's not a documented feature, but we could document it, or perhaps
better provide a "XAPIAN_NO_DEPRECATED_WARNINGS" macro the user can
define which does this internally (in case we find we need to change
how that macro works).  I think ideally we want the policy which API
users find most useful, but if different people want different things,
then this is one solution.

Cheers,
    Olly