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 http://wiki.apache.org/lucene-java/BackwardsCompatibility 
>>  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: java-dev-unsubscribe@lucene.apache.org
>>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>>
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org