[Xapian-devel] Deprecation Policy

[Olly Betts]

On Wed, Apr 11, 2007 at 12:21:28PM +0100, James Aylett wrote:
> On Wed, Apr 11, 2007 at 11:58:55AM +0100, Olly Betts wrote:
> > Richard wrote:
> > >  - 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.
> 
> Providing structures are only ever managed by Xapian, and only ever
> used by pointer, it's not an issue. When structure sizes change it can
> become an issue; I can't remember whether this is relevant for Xapian.

Not generally - most of the classes use the PIMPL idiom, and the
externally visible API structure just holds a pointer to reference
counted internals which are handled only inside the library.

Because of issues with templated constructors, Query::Internal is
currently declared in the external API header.  I'd love to fix that
but attempts so far have failed.

The simpler iterators aren't PIMPL either, and neither are some
auxiliary classes (Xapian::Stopper for example).

> I think we should *try* to keep ABI compatability within a release
> series, but not be dogmatic about it. The virtue of ABI compat is that
> security updates can be deployed straightforward testing and no
> pain.

And packaging is easier, for similar reasons.  I think we should 
only bump the ABI if there's a very good reason.

> Unless we go to a situation where release series don't get new
> features, I don't think ABI compat is a huge issue for us.

I think for now each release series will probably need to move to "no
new features" mode as we prepare to move to the next (as 0.9 currently
essentially is).  But this isn't something we need to nail down right
now, and I'd rather focus on getting 1.0 released than be diverted into
lengthy discussions of directions after that.

> > > 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.
> 
> I think we should actually write more narrative "how to move from
> 1.X.* to 1.X+1.0" documents. It shouldn't be difficult; it just needs
> a little bit more structure than a dump of the replacement comments
> for deprecated methods now removed.

There's a place for both - a narrative is useful for reading before
migration, but when you type "make" on your application and it fails to
find "Enquire::set_sorting()" then a table mapping "this old -> that new"
is more helpful than paragraphs of prose.

My main point is that we shouldn't just delete the helpful comments
I've added for each deprecated method as they are still going to be
useful.

Cheers,
    Olly