You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Michael Busch <bu...@gmail.com> on 2008/10/21 23:45:28 UTC
[VOTE] Relax backwards-compatibility policy for package-protected
APIs
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". 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.
Here is my +1.
-Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Posted by DM Smith <dm...@gmail.com>.
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: java-dev-unsubscribe@lucene.apache.org
>>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>>
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected
APIs
Posted by Michael Busch <bu...@gmail.com>.
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?
>
OK, it seems that everyone is ok with this. I will update the wiki.
-Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected
APIs
Posted by Andrzej Bialecki <ab...@getopt.org>.
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.
Definitely +1 on this strategy, so long as it's clearly documented.
Example: I'm working on a new version of Luke, where I use some of the
internal and experimental APIs (e.g. the commit points), being aware
that things may break in nasty ways if I upgrade to a different version
of Lucene. I've been forewarned, and I won't complain. :)
--
Best regards,
Andrzej Bialecki <><
___. ___ ___ ___ _ _ __________________________________
[__ || __|__/|__||\/| Information Retrieval, Semantic Web
___|||__|| \| || | Embedded Unix, System Integration
http://www.sigram.com Contact: info at sigram dot com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Posted by Michael McCandless <lu...@mikemccandless.com>.
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: java-dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected APIs
Posted by Grant Ingersoll <gs...@apache.org>.
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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected
APIs
Posted by Michael Busch <bu...@gmail.com>.
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: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: [VOTE] Relax backwards-compatibility policy for package-protected
APIs
Posted by Doug Cutting <cu...@apache.org>.
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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org