lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From DM Smith <>
Subject Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Date Wed, 22 Oct 2008 11:21:22 GMT

On Oct 22, 2008, at 5:27 AM, Michael McCandless wrote:

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

A common practice in marking package private is to do the following:
/* private */ int xxxx;
That makes it abundantly clear that the API is logically private.

> Mike
> 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:

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

View raw message