[Xapian-devel] Deprecation Policy

Richard Boulton richard at lemurconsulting.com
Wed Apr 11 10:07:19 BST 2007


When going through the xapian bindings yesterday, I noticed that several 
of the methods were not wrapped for Ruby because they were deprecated at 
the time the ruby bindings were created.  I filed a bug (#126) saying 
that they should be removed entirely, which led to the suggestion from 
Olly that it would be good to make a semi-formal policy about 
deprecating features.  I've written such a document, and checked it into 
SVN (as docs/deprecation.rst).

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!

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.

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

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


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.  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'll populate the lists for the bindings shortly, and we should add 
corresponding lists for omega (covering its CGI parameters and omegascript).

-- 
Richard



More information about the Xapian-devel mailing list