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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
