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