lucene-dev mailing list archives

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

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.


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

View raw message