[Xapian-devel] Deprecation Policy

[James Aylett]

On Wed, Apr 11, 2007 at 11:58:55AM +0100, Olly Betts wrote:

> Except that I think deprecating in X.Y.0 should permit removal in X.Y+1.0.
> I think this might be clearer in less formal language with a couple of
> examples.

+1

> >  - 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.
> 
> Yes.  I think this needs to play by the same rules as not removing
> deprecated methods.  Otherwise we're just effectively removing
> functionality without deprecating it.

+1

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

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

> >  - 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?
> 
> As ammended above, (i.e. "deprecate in 1.0.1-1.1.X, remove in 1.2.0") I
> think that's reasonable.

+1

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

J

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