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