[Xapian-discuss] Deprecation policy question

[Richard Boulton]

Olly and I have been discussing details of our policy for deprecating 
features, and we thought it would be useful to canvas users opinions on 
a particular aspect.

 From time to time, we remove features from the library (usually because 
we have a better replacement).  To make life easier for users, we've 
been following a deprecation policy, so that users are given plenty of 
warning of features which are about to be removed, and are given 
suggestions of how to change their code.  This policy states that 
(whenever possible) when a feature is marked as deprecated at a 
particular release of Xapian, the feature will continue to be present 
and unchanged for a full release cycle.  For example, if a feature is 
deprecated in version 1.0.3, it will remain usable in Xapian throughout 
the 1.0.x and 1.1.x release series, and finally be removed in release 1.2.0.

There are several ways in which a feature is advertised as deprecated:

1. The deprecation is listed in the NEWS file at the time it is first 
marked as deprecated (ie, in version 1.0.3 in the earlier example).
2. The deprecation is described in documentation comments in the API, 
with a special marker, so that the list of current deprecations appears 
in the API documentation (at 
http://www.xapian.org/docs/apidoc/html/deprecated.html)
3. The deprecation is listed in a table of all current and past 
deprecations in docs/deprecation.rst, which produces the HTML version
http://www.xapian.org/docs/deprecation.html
4. A macro is used to mark features as deprecated, so that compilers 
will emit a warning when the deprecated feature is used.

The point which we wish to canvas opinion on is this final one.  The 
question is whether we should add the macro to features at the time we 
initially mark them as deprecated, or should wait until the next release 
series.  The advantage of adding the macro immediately is that users get 
as much warning as possible - but the disadvantage is that code which 
compiled fine at the start of a release series suddenly starts producing 
warnings (and indeed, fails to compile if -Werror is being used).

There are actually 3 options:

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.

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.

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.

Which of these options seem most helpful to you?

-- 
Richard