[Xapian-discuss] Deprecation policy question

[James Aylett]

On Mon, Sep 24, 2007 at 09:05:36AM +0100, Richard Boulton wrote:

> 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.

I see the argument for not wanting to do this because of
-Werror. However (and see below for more) I think this is still a
better choice than the alternatives.

> 2. Always wait until the next release series to add the deprecation 
> macro (so, at version 1.1.0 in the above example).  This is good because 
>  code which compiled without warnings at a x.y.0 release will continue 
> to compile without warnings for the rest of that release series, but 
> does delay the compiler warning about changes needed to code.

This feels to me to be the most user-focussed way of doing it, HOWEVER
it means the macro isn't a true deprecation macro. It's instead a
notification of imminent breakage - kind of raising the warning level.

For that reason I'd vote for (1). People who are compiling -Werror are
*wanting* minor things to stop the system from building (and indeed
tend to develop in a different kind of vibe to people who are using
default compiler flags and ignoring warnings). They want to raise the
warning level. They are generally the sorts of people who want to
float on the *front* line of the (released version of the) library,
rather than a little behind the wave.

While personally I think everyone should compile -Werror, I don't
think this will discourage those who want to any more than things like
the vile type munging you have to do throughout the STL when writing
your own code.

I also suspect that the majority (and an increasing number) of users
of Xapian won't actually be writing in C++ anyway, so putting
deprecation into code as soon as possible helps anyone writing extra
library layers, or reasonable-sized applications, to ensure they don't
miss anything. That is (again, I suspect) mostly going to be the
Xapian developers + under half a dozen others, all of whom are likely
to follow things reasonably closely, and would really benefit from
this tool to make sure we don't miss deprecated features.

> 3. Add the deprecation macro if and only if there is an alternative 
> which works with the most recent x.y.0 release.  If there is, users can 
> change their code such that it compiles with all releases of Xapian 
> within a given release series without warnings, but not all code which 
> compiles at x.y.0 will continue to compile without warnings.

This feels wrong to me, mostly because the rule is more
complex. Simpler rules are better.

Conversely, it sounds wrong to me to introduce that situation in the
first place. Do we have an example of a deprecation change introduced
within a release series that it's impossible to compile smoothly
across? We should be avoiding those situations strenuously IMHO.

J

-- 
/--------------------------------------------------------------------------\
  James Aylett                                                  xapian.org
  james at tartarus.org                               uncertaintydivision.org