Mailing-List: contact java-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@lucene.apache.org
Received-SPF: pass (athena.apache.org: domain of dmsmith555@gmail.com
 designates 74.125.44.29 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=message-id:from:to:in-reply-to:content-type
         :content-transfer-encoding:mime-version:subject:date:references
         :x-mailer;
        b=mKBUrWYMSafnYkZgMkT7td6oSWYec4eu+/yUv+ckJ1i/gLBghEFB38LfCPfTI1kCJ4
         ENqy8XlMbL8brkCIOkvRYevc4IfSzHuA8rLan33XPjzRVNzjdvGm3y64U3kNEp3nM5vP
         zwNc22WUdc+r25bRlXPdyiXF8ZExhPrs18Uvo=
Message-Id: <CA4A7ED9-E747-4A70-A338-5BA233CFCD77@gmail.com>
From: DM Smith <dmsmith555@gmail.com>
To: java-dev@lucene.apache.org
In-Reply-To: <5E2DEA6D-FB4B-462D-91C5-091D72EEDA5C@mikemccandless.com>
Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Apple Message framework v929.2)
Subject: Re: [VOTE] Relax backwards-compatibility policy for package-protected
 APIs
Date: Wed, 22 Oct 2008 07:21:22 -0400
References: <48FE4D78.2070505@gmail.com> <48FE51DD.8090006@apache.org>
 <48FE5C78.6080908@gmail.com>
 <5E2DEA6D-FB4B-462D-91C5-091D72EEDA5C@mikemccandless.com>


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