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