lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael McCandless <>
Subject Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Date Wed, 22 Oct 2008 09:27:42 GMT

I think *not* having to maintain back compat of the package private  
APIs is very important to keeping our freedom (and sanity!) to  
continue to improve Lucene.  This is similar to marking a new API as  
experimental and subject to suddenly change in the next release: it  
reserves our future freedom.

Still, I think it's OK if advanced sources want to tap into package  
private APIs as long as we've made this policy clear.

I agree we should explicitly call this out, clearly, in the  
BackwardsCompatbility wiki -- Michael can you update it?


Michael Busch wrote:

> Doug Cutting wrote:
>> Michael Busch wrote:
>>> Currently Lucene's backwards compatibility policy states: "That's  
>>> to say, any code developed against X.0 should continue to run  
>>> without alteration against all X.N releases." In LUCENE-1422 the  
>>> question came up if this statement should apply to public and  
>>> protected APIs only or also to package-private APIs.
>>> I'm proposing to exempt the package-private APIs from this strict  
>>> backwards compatibility rule and declare it as "expert methods".
>> Package-private and expert are different categories.
>> Expert methods are things that most folks can ignore when reading  
>> the documentation.  They're intended for advanced, unusual cases.   
>> A public or protected expert method has all the back-compatibility  
>> requirements of a non-expert method.
>> But package-private methods are not for public consumption.  Code  
>> that relies on calling package-private methods may be broken by an  
>> otherwise back-compatible upgrade.  Package-private is not for  
>> external use, where external means outside of Lucene Java source  
>> tree.
>>> Though, only deprecated package-private methods are allowed to be  
>>> removed. This means that at least one X.Y-> X.Y+1 or X.Y->X+1.0  
>>> release must be shipped in which the APIs are marked as deprecated  
>>> to give the users the chance to remove dependencies on these  
>>> methods. If this vote passes we will add appropriate information  
>>> to CHANGES.txt and the next release announcement.
>> I don't think we should ever be required to deprecate package- 
>> private stuff.  It can be changed without notice.  If someone needs  
>> a feature to work across multiple releases, then they should get a  
>> public, supported version of it.  Package private is by definition  
>> not public and hence not supported.
> Even better. That was actually my understanding before I encountered  
> the deprecated Token members. So if this is the agreement already  
> then there is no need for a vote, unless anybody has concerns with  
> this? We should probably update

>  and make it clear that "complete API back-compatiblity" only  
> includes public and protected APIs.
>> That said, if there's a case where some particular package-private  
>> feature is known to be widely used (a bad situation, mind you) then  
>> it might be kind to deprecate it rather than remove it, but folks  
>> should not rely on this in general as a policy.  Otherwise we can't  
>> freely use package private, and it's a nice way to break internal  
>> implementations into multiple classes.
> Agreed.
>> Doug
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail:
>> For additional commands, e-mail:
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message