On Oct 21, 2008, at 6:49 PM, 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.
+1 on updating the wiki, and +1 on the proposal.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
