lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Grant Ingersoll <>
Subject Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Date Wed, 22 Oct 2008 12:06:14 GMT

On Oct 21, 2008, at 6:49 PM, 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.

+1 on updating the wiki, and +1 on the proposal.

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

View raw message