lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Busch <>
Subject Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Date Tue, 21 Oct 2008 22:49:28 GMT
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.

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

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

View raw message