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 2009/06/16 12:37:40 UTC
Proposal for changing the backwards-compatibility policy
Probably everyone is thinking right now "Oh no! Not again!". I admit I
didn't fully read the incredibly long recent thread about
backwards-compatibility, so maybe what I'm about to propose has been
proposed already. In that case my apologies in advance.
Rather than discussing our current backwards-compatibility policy
again, I'd like to make here a concrete proposal for changing the policy
after Lucene 3.0 is released.
I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
use different names; just for convenience here...)
1. The file format backwards-compatiblity policy will remain unchanged;
i.e. Lucene X.Y supports reading all indexes written with Lucene
X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
indexes.
2. Deprecated public and protected APIs can be removed if they have
been released in at least one major or minor release. E.g. an 3.1
API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
(if 4.0 comes after 3.2).
3. No public or protected APIs are changed in a bugfix release; except
if a severe bug can't be changed otherwise.
4. Each release will have release notes with a new section
"Incompatible changes", which lists, as the names says, all changes that
break backwards compatibility. The list should also have information
about how to convert to the new API. I think the eclipse releases
have such a release notes section.
The big change here apparently is 2. Consider the current situation:
We can release e.g. the new TokenStream API with 2.9; then we can
remove it a month later in 3.0, while still complying with our current
backwards-compatibility policy. A transition period of one month is
very short for such an important API. On the other hand, a transition
period of presumably >2 years, until 4.0 is released, seems very long
to stick with a deprecated API that clutters the APIs and docs. With
the proposed change, we couldn't do that. Given our current release
schedule, the transition period would at least be 6-9 months, which
seems a very reasonable timeframe.
We should also not consider 2. as a must. I.e. we don't *have* to
deprecate after one major or minor release already. We could for a
very popular API like the TokenStream API send a mail to java-user,
asking if people need more transition time and be flexible.
I think this policy is much more dynamic and flexible, but should
still give our users enough confidence. It also removes the need to
do things just for the sake of the current policy rather than because
they make the most sense, like our somewhat goofy X.9 releases. :)
Just to make myself clear: I think we should definitely stick with our
2.9 and 3.0 plans and change the policy afterwards.
My +1 to all 4 points above.
-Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Mark Miller <ma...@gmail.com>.
Just to cat call from the corner over here:
So unless you update on *every* minor release, from a users perspective,
this is the same as tossing out API back compat (though still with the
option to keep what we want around as long as we want) ?
Michael Busch wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes
> that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
--
- Mark
http://www.lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
Well I'd actually hope that there will be significantly less need to do
these "tricks" to get around the new policy.
I'll open a JIRA issue and we can use it to work on the exact wording.
Michael
On 6/16/09 9:03 AM, Mark Miller wrote:
> Right - I'm not saying that the users should trump the devs, just
> curious what the response will be, if any.
>
> I also think that when we update the back compat policy, there should
> be wording that stresses where we should use our new powers carefully
> (eg common API's and such).
>
> And we should update it to be more accurate - we should mention how we
> have lots of exceptions and experimental API's that we use to get
> around what is there now. I imagine that will continue to an extent.
> Our policy should allow our current behavior :)
>
> - Mark
>
> Michael Busch wrote:
>> Fair enough. We certainly want our users to understand our reasons
>> for these changes, and keep their trust that we're making our best
>> efforts to keep upgrading as effortless as possible.
>>
>> However, there will always be someone who is not happy with such a
>> change. But if the vast majority of the users doesn't complain, we
>> should be good to go.
>>
>> I'll send a mail to java-user soonish.
>>
>> Michael
>>
>> On 6/16/09 7:01 AM, Mark Miller wrote:
>>> I'd be interested in what the users list has to say.
>>>
>>> With this many +1's, seems reasonable to take it over there.
>>>
>>> - Mark
>>>
>>> Grant Ingersoll wrote:
>>>> +1 on everything. This is the sanity we need, especially #2.
>>>> Thanks for bringing this up again.
>>>>
>>>> I'd add a slight mod to #2 that I think helps further communicate
>>>> to users our expectations (marked by my initials GSI) by employing
>>>> some convention in our @deprecated comments:
>>>> 2. Deprecated public and protected APIs can be removed if they have
>>>> been released in at least one major or minor release. E.g. an 3.1
>>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>>> (if 4.0 comes after 3.2).
>>>> GSI: Furthermore, the Deprecation tag comment will state the
>>>> minimum version when this API is to be removed, e.g.
>>>> @deprecated See #fooBar(). Will be removed in 3.3
>>>> or
>>>> @deprecated See #fooBar(). Will be removed in 3.3 or later.
>>>>
>>>> Also, while #4 covers breaking Interfaces, it would be nice if we
>>>> had some way of stating that an interface is going to change,
>>>> assuming we are thinking about it. Alternatively, maybe we should
>>>> just out right label all Interfaces as being subject to change.
>>>> For instance, if we want to add to Fieldable, perhaps we could say,
>>>> in the comments, something like: We expect to add the following to
>>>> Fieldable: getWhizBangValue() in version 3.3. This will break any
>>>> implementations of Fieldable. Still, I'm fine with #4 as stated.
>>>>
>>>> Finally, I still think we all agree that when possible, we should
>>>> make _reasonable_ efforts to maintain back compatibility.
>>>>
>>>> -Grant
>>>>
>>>>
>>>> On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
>>>>
>>>>> Probably everyone is thinking right now "Oh no! Not again!". I
>>>>> admit I
>>>>> didn't fully read the incredibly long recent thread about
>>>>> backwards-compatibility, so maybe what I'm about to propose has been
>>>>> proposed already. In that case my apologies in advance.
>>>>>
>>>>> Rather than discussing our current backwards-compatibility policy
>>>>> again, I'd like to make here a concrete proposal for changing the
>>>>> policy
>>>>> after Lucene 3.0 is released.
>>>>>
>>>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can
>>>>> later
>>>>> use different names; just for convenience here...)
>>>>>
>>>>> 1. The file format backwards-compatiblity policy will remain
>>>>> unchanged;
>>>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>>>> indexes.
>>>>>
>>>>> 2. Deprecated public and protected APIs can be removed if they have
>>>>> been released in at least one major or minor release. E.g. an 3.1
>>>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>>>> (if 4.0 comes after 3.2).
>>>>>
>>>>> 3. No public or protected APIs are changed in a bugfix release;
>>>>> except
>>>>> if a severe bug can't be changed otherwise.
>>>>>
>>>>> 4. Each release will have release notes with a new section
>>>>> "Incompatible changes", which lists, as the names says, all
>>>>> changes that
>>>>> break backwards compatibility. The list should also have
>>>>> information
>>>>> about how to convert to the new API. I think the eclipse releases
>>>>> have such a release notes section.
>>>>>
>>>>>
>>>>> The big change here apparently is 2. Consider the current situation:
>>>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>>>> remove it a month later in 3.0, while still complying with our
>>>>> current
>>>>> backwards-compatibility policy. A transition period of one month is
>>>>> very short for such an important API. On the other hand, a transition
>>>>> period of presumably >2 years, until 4.0 is released, seems very long
>>>>> to stick with a deprecated API that clutters the APIs and docs. With
>>>>> the proposed change, we couldn't do that. Given our current release
>>>>> schedule, the transition period would at least be 6-9 months, which
>>>>> seems a very reasonable timeframe.
>>>>>
>>>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>>>> deprecate after one major or minor release already. We could for a
>>>>> very popular API like the TokenStream API send a mail to java-user,
>>>>> asking if people need more transition time and be flexible.
>>>>>
>>>>> I think this policy is much more dynamic and flexible, but should
>>>>> still give our users enough confidence. It also removes the need to
>>>>> do things just for the sake of the current policy rather than because
>>>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>>>
>>>>> Just to make myself clear: I think we should definitely stick with
>>>>> our
>>>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>>>
>>>>> My +1 to all 4 points above.
>>>>>
>>>>> -Michael
>>>>>
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> 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: Proposal for changing the backwards-compatibility policy
Posted by Mark Miller <ma...@gmail.com>.
Right - I'm not saying that the users should trump the devs, just
curious what the response will be, if any.
I also think that when we update the back compat policy, there should be
wording that stresses where we should use our new powers carefully (eg
common API's and such).
And we should update it to be more accurate - we should mention how we
have lots of exceptions and experimental API's that we use to get around
what is there now. I imagine that will continue to an extent. Our policy
should allow our current behavior :)
- Mark
Michael Busch wrote:
> Fair enough. We certainly want our users to understand our reasons for
> these changes, and keep their trust that we're making our best efforts
> to keep upgrading as effortless as possible.
>
> However, there will always be someone who is not happy with such a
> change. But if the vast majority of the users doesn't complain, we
> should be good to go.
>
> I'll send a mail to java-user soonish.
>
> Michael
>
> On 6/16/09 7:01 AM, Mark Miller wrote:
>> I'd be interested in what the users list has to say.
>>
>> With this many +1's, seems reasonable to take it over there.
>>
>> - Mark
>>
>> Grant Ingersoll wrote:
>>> +1 on everything. This is the sanity we need, especially #2.
>>> Thanks for bringing this up again.
>>>
>>> I'd add a slight mod to #2 that I think helps further communicate to
>>> users our expectations (marked by my initials GSI) by employing some
>>> convention in our @deprecated comments:
>>> 2. Deprecated public and protected APIs can be removed if they have
>>> been released in at least one major or minor release. E.g. an 3.1
>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>> (if 4.0 comes after 3.2).
>>> GSI: Furthermore, the Deprecation tag comment will state the minimum
>>> version when this API is to be removed, e.g.
>>> @deprecated See #fooBar(). Will be removed in 3.3
>>> or
>>> @deprecated See #fooBar(). Will be removed in 3.3 or later.
>>>
>>> Also, while #4 covers breaking Interfaces, it would be nice if we
>>> had some way of stating that an interface is going to change,
>>> assuming we are thinking about it. Alternatively, maybe we should
>>> just out right label all Interfaces as being subject to change. For
>>> instance, if we want to add to Fieldable, perhaps we could say, in
>>> the comments, something like: We expect to add the following to
>>> Fieldable: getWhizBangValue() in version 3.3. This will break any
>>> implementations of Fieldable. Still, I'm fine with #4 as stated.
>>>
>>> Finally, I still think we all agree that when possible, we should
>>> make _reasonable_ efforts to maintain back compatibility.
>>>
>>> -Grant
>>>
>>>
>>> On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
>>>
>>>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>>>> didn't fully read the incredibly long recent thread about
>>>> backwards-compatibility, so maybe what I'm about to propose has been
>>>> proposed already. In that case my apologies in advance.
>>>>
>>>> Rather than discussing our current backwards-compatibility policy
>>>> again, I'd like to make here a concrete proposal for changing the
>>>> policy
>>>> after Lucene 3.0 is released.
>>>>
>>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>>>> use different names; just for convenience here...)
>>>>
>>>> 1. The file format backwards-compatiblity policy will remain
>>>> unchanged;
>>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>>> indexes.
>>>>
>>>> 2. Deprecated public and protected APIs can be removed if they have
>>>> been released in at least one major or minor release. E.g. an 3.1
>>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>>> (if 4.0 comes after 3.2).
>>>>
>>>> 3. No public or protected APIs are changed in a bugfix release; except
>>>> if a severe bug can't be changed otherwise.
>>>>
>>>> 4. Each release will have release notes with a new section
>>>> "Incompatible changes", which lists, as the names says, all
>>>> changes that
>>>> break backwards compatibility. The list should also have information
>>>> about how to convert to the new API. I think the eclipse releases
>>>> have such a release notes section.
>>>>
>>>>
>>>> The big change here apparently is 2. Consider the current situation:
>>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>>> remove it a month later in 3.0, while still complying with our current
>>>> backwards-compatibility policy. A transition period of one month is
>>>> very short for such an important API. On the other hand, a transition
>>>> period of presumably >2 years, until 4.0 is released, seems very long
>>>> to stick with a deprecated API that clutters the APIs and docs. With
>>>> the proposed change, we couldn't do that. Given our current release
>>>> schedule, the transition period would at least be 6-9 months, which
>>>> seems a very reasonable timeframe.
>>>>
>>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>>> deprecate after one major or minor release already. We could for a
>>>> very popular API like the TokenStream API send a mail to java-user,
>>>> asking if people need more transition time and be flexible.
>>>>
>>>> I think this policy is much more dynamic and flexible, but should
>>>> still give our users enough confidence. It also removes the need to
>>>> do things just for the sake of the current policy rather than because
>>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>>
>>>> Just to make myself clear: I think we should definitely stick with our
>>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>>
>>>> My +1 to all 4 points above.
>>>>
>>>> -Michael
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> 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
>
--
- Mark
http://www.lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
Fair enough. We certainly want our users to understand our reasons for
these changes, and keep their trust that we're making our best efforts
to keep upgrading as effortless as possible.
However, there will always be someone who is not happy with such a
change. But if the vast majority of the users doesn't complain, we
should be good to go.
I'll send a mail to java-user soonish.
Michael
On 6/16/09 7:01 AM, Mark Miller wrote:
> I'd be interested in what the users list has to say.
>
> With this many +1's, seems reasonable to take it over there.
>
> - Mark
>
> Grant Ingersoll wrote:
>> +1 on everything. This is the sanity we need, especially #2.
>> Thanks for bringing this up again.
>>
>> I'd add a slight mod to #2 that I think helps further communicate to
>> users our expectations (marked by my initials GSI) by employing some
>> convention in our @deprecated comments:
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>> GSI: Furthermore, the Deprecation tag comment will state the minimum
>> version when this API is to be removed, e.g.
>> @deprecated See #fooBar(). Will be removed in 3.3
>> or
>> @deprecated See #fooBar(). Will be removed in 3.3 or later.
>>
>> Also, while #4 covers breaking Interfaces, it would be nice if we had
>> some way of stating that an interface is going to change, assuming we
>> are thinking about it. Alternatively, maybe we should just out right
>> label all Interfaces as being subject to change. For instance, if we
>> want to add to Fieldable, perhaps we could say, in the comments,
>> something like: We expect to add the following to Fieldable:
>> getWhizBangValue() in version 3.3. This will break any
>> implementations of Fieldable. Still, I'm fine with #4 as stated.
>>
>> Finally, I still think we all agree that when possible, we should
>> make _reasonable_ efforts to maintain back compatibility.
>>
>> -Grant
>>
>>
>> On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
>>
>>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>>> didn't fully read the incredibly long recent thread about
>>> backwards-compatibility, so maybe what I'm about to propose has been
>>> proposed already. In that case my apologies in advance.
>>>
>>> Rather than discussing our current backwards-compatibility policy
>>> again, I'd like to make here a concrete proposal for changing the
>>> policy
>>> after Lucene 3.0 is released.
>>>
>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>>> use different names; just for convenience here...)
>>>
>>> 1. The file format backwards-compatiblity policy will remain unchanged;
>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>> indexes.
>>>
>>> 2. Deprecated public and protected APIs can be removed if they have
>>> been released in at least one major or minor release. E.g. an 3.1
>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>> (if 4.0 comes after 3.2).
>>>
>>> 3. No public or protected APIs are changed in a bugfix release; except
>>> if a severe bug can't be changed otherwise.
>>>
>>> 4. Each release will have release notes with a new section
>>> "Incompatible changes", which lists, as the names says, all
>>> changes that
>>> break backwards compatibility. The list should also have information
>>> about how to convert to the new API. I think the eclipse releases
>>> have such a release notes section.
>>>
>>>
>>> The big change here apparently is 2. Consider the current situation:
>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>> remove it a month later in 3.0, while still complying with our current
>>> backwards-compatibility policy. A transition period of one month is
>>> very short for such an important API. On the other hand, a transition
>>> period of presumably >2 years, until 4.0 is released, seems very long
>>> to stick with a deprecated API that clutters the APIs and docs. With
>>> the proposed change, we couldn't do that. Given our current release
>>> schedule, the transition period would at least be 6-9 months, which
>>> seems a very reasonable timeframe.
>>>
>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>> deprecate after one major or minor release already. We could for a
>>> very popular API like the TokenStream API send a mail to java-user,
>>> asking if people need more transition time and be flexible.
>>>
>>> I think this policy is much more dynamic and flexible, but should
>>> still give our users enough confidence. It also removes the need to
>>> do things just for the sake of the current policy rather than because
>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>
>>> Just to make myself clear: I think we should definitely stick with our
>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>
>>> My +1 to all 4 points above.
>>>
>>> -Michael
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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: Proposal for changing the backwards-compatibility policy
Posted by Mark Miller <ma...@gmail.com>.
I'd be interested in what the users list has to say.
With this many +1's, seems reasonable to take it over there.
- Mark
Grant Ingersoll wrote:
> +1 on everything. This is the sanity we need, especially #2. Thanks
> for bringing this up again.
>
> I'd add a slight mod to #2 that I think helps further communicate to
> users our expectations (marked by my initials GSI) by employing some
> convention in our @deprecated comments:
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
> GSI: Furthermore, the Deprecation tag comment will state the minimum
> version when this API is to be removed, e.g.
> @deprecated See #fooBar(). Will be removed in 3.3
> or
> @deprecated See #fooBar(). Will be removed in 3.3 or later.
>
> Also, while #4 covers breaking Interfaces, it would be nice if we had
> some way of stating that an interface is going to change, assuming we
> are thinking about it. Alternatively, maybe we should just out right
> label all Interfaces as being subject to change. For instance, if we
> want to add to Fieldable, perhaps we could say, in the comments,
> something like: We expect to add the following to Fieldable:
> getWhizBangValue() in version 3.3. This will break any
> implementations of Fieldable. Still, I'm fine with #4 as stated.
>
> Finally, I still think we all agree that when possible, we should make
> _reasonable_ efforts to maintain back compatibility.
>
> -Grant
>
>
> On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
>
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>> indexes.
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>> if a severe bug can't be changed otherwise.
>>
>> 4. Each release will have release notes with a new section
>> "Incompatible changes", which lists, as the names says, all changes
>> that
>> break backwards compatibility. The list should also have information
>> about how to convert to the new API. I think the eclipse releases
>> have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably >2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> 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
>
--
- Mark
http://www.lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
Sounds good, Grant. I'll open a task to change the policy with target
release=3.0.
Michael
On 6/16/09 6:53 AM, Grant Ingersoll wrote:
> +1 on everything. This is the sanity we need, especially #2. Thanks
> for bringing this up again.
>
> I'd add a slight mod to #2 that I think helps further communicate to
> users our expectations (marked by my initials GSI) by employing some
> convention in our @deprecated comments:
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
> GSI: Furthermore, the Deprecation tag comment will state the minimum
> version when this API is to be removed, e.g.
> @deprecated See #fooBar(). Will be removed in 3.3
> or
> @deprecated See #fooBar(). Will be removed in 3.3 or later.
>
> Also, while #4 covers breaking Interfaces, it would be nice if we had
> some way of stating that an interface is going to change, assuming we
> are thinking about it. Alternatively, maybe we should just out right
> label all Interfaces as being subject to change. For instance, if we
> want to add to Fieldable, perhaps we could say, in the comments,
> something like: We expect to add the following to Fieldable:
> getWhizBangValue() in version 3.3. This will break any
> implementations of Fieldable. Still, I'm fine with #4 as stated.
>
> Finally, I still think we all agree that when possible, we should make
> _reasonable_ efforts to maintain back compatibility.
>
> -Grant
>
>
> On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
>
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>> indexes.
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>> if a severe bug can't be changed otherwise.
>>
>> 4. Each release will have release notes with a new section
>> "Incompatible changes", which lists, as the names says, all changes
>> that
>> break backwards compatibility. The list should also have information
>> about how to convert to the new API. I think the eclipse releases
>> have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably >2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> 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: Proposal for changing the backwards-compatibility policy
Posted by Grant Ingersoll <gs...@apache.org>.
+1 on everything. This is the sanity we need, especially #2. Thanks
for bringing this up again.
I'd add a slight mod to #2 that I think helps further communicate to
users our expectations (marked by my initials GSI) by employing some
convention in our @deprecated comments:
2. Deprecated public and protected APIs can be removed if they have
been released in at least one major or minor release. E.g. an 3.1
API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
(if 4.0 comes after 3.2).
GSI: Furthermore, the Deprecation tag comment will state the minimum
version when this API is to be removed, e.g.
@deprecated See #fooBar(). Will be removed in 3.3
or
@deprecated See #fooBar(). Will be removed in 3.3 or later.
Also, while #4 covers breaking Interfaces, it would be nice if we had
some way of stating that an interface is going to change, assuming we
are thinking about it. Alternatively, maybe we should just out right
label all Interfaces as being subject to change. For instance, if we
want to add to Fieldable, perhaps we could say, in the comments,
something like: We expect to add the following to Fieldable:
getWhizBangValue() in version 3.3. This will break any
implementations of Fieldable. Still, I'm fine with #4 as stated.
Finally, I still think we all agree that when possible, we should make
_reasonable_ efforts to maintain back compatibility.
-Grant
On Jun 16, 2009, at 6:37 AM, Michael Busch wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the
> policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain
> unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all
> changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> 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: Proposal for changing the backwards-compatibility policy
Posted by Shai Erera <se...@gmail.com>.
Also, much shorter text to read :)
You're right, Michael's is 484 words, mine was 691. But in my defense, I did
offer two more changes, that were later brought up on this thread (summing
to 563 words) :).
Anyway, I'm glad it's kept alive and hopefully things will change.
Shai
On Tue, Jun 16, 2009 at 7:09 PM, Mark Miller <ma...@gmail.com> wrote:
> I would guess you hit what I call "thread fatigue" by the time you summed
> that up :)
>
> Michael hasn't been around for a bit - perhaps it was easier for him to
> spawn a new thread.
>
> Also, much shorter text to read :)
>
> Shai Erera wrote:
>
>> Ahh ... I wish I had finished
>> http://www.nabble.com/Re%3A-Lucene%27s-default-settings---back-compatibility-p23792927.htmlwith +1 of my own. Guess that's what was missing to get it to closure :).
>>
>> Shai
>>
>> On Tue, Jun 16, 2009 at 7:03 PM, Michael Busch <buschmic@gmail.com<mailto:
>> buschmic@gmail.com>> wrote:
>>
>> I'd suggest to treat a runtime change like an API change (unless
>> it's fixing a bug of course),
>> i.e. giving a warning, providing a switch, switching the default
>> behavior only after a major
>> or minor release was around that had the warning/switch.
>>
>> Michael
>>
>>
>>
>> On 6/16/09 8:54 AM, Earwin Burrfoot wrote:
>>
>>> Oh yes! Again!
>>> +1
>>>
>>> One point is missing. What about incompatible behavioral changes that
>>> do not touch API and file format?
>>> Like posIncr=0 at the first token in stream, or analyzer fixes, or
>>> something along these lines.
>>>
>>> Are we free to introduce them in a minor release without warning, or
>>> are we going to warn one release before the change, or do we provide
>>> old-behaviour switches that are deprecated since their birth, or we
>>> keep said switches for a couple of major releases?
>>>
>>>
>>> On Tue, Jun 16, 2009 at 14:37, Michael Busch<bu...@gmail.com>
>>> <ma...@gmail.com> wrote:
>>>
>>>
>>>> Probably everyone is thinking right now "Oh no! Not again!". I admit
>>>> I
>>>> didn't fully read the incredibly long recent thread about
>>>> backwards-compatibility, so maybe what I'm about to propose has been
>>>> proposed already. In that case my apologies in advance.
>>>>
>>>> Rather than discussing our current backwards-compatibility policy
>>>> again, I'd like to make here a concrete proposal for changing the
>>>> policy
>>>> after Lucene 3.0 is released.
>>>>
>>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can
>>>> later
>>>> use different names; just for convenience here...)
>>>>
>>>> 1. The file format backwards-compatiblity policy will remain
>>>> unchanged;
>>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>>> indexes.
>>>>
>>>> 2. Deprecated public and protected APIs can be removed if they have
>>>> been released in at least one major or minor release. E.g. an 3.1
>>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>>> (if 4.0 comes after 3.2).
>>>>
>>>> 3. No public or protected APIs are changed in a bugfix release;
>>>> except
>>>> if a severe bug can't be changed otherwise.
>>>>
>>>> 4. Each release will have release notes with a new section
>>>> "Incompatible changes", which lists, as the names says, all changes
>>>> that
>>>> break backwards compatibility. The list should also have
>>>> information
>>>> about how to convert to the new API. I think the eclipse releases
>>>> have such a release notes section.
>>>>
>>>>
>>>> The big change here apparently is 2. Consider the current situation:
>>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>>> remove it a month later in 3.0, while still complying with our
>>>> current
>>>> backwards-compatibility policy. A transition period of one month is
>>>> very short for such an important API. On the other hand, a transition
>>>> period of presumably >2 years, until 4.0 is released, seems very long
>>>> to stick with a deprecated API that clutters the APIs and docs. With
>>>> the proposed change, we couldn't do that. Given our current release
>>>> schedule, the transition period would at least be 6-9 months, which
>>>> seems a very reasonable timeframe.
>>>>
>>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>>> deprecate after one major or minor release already. We could for a
>>>> very popular API like the TokenStream API send a mail to java-user,
>>>> asking if people need more transition time and be flexible.
>>>>
>>>> I think this policy is much more dynamic and flexible, but should
>>>> still give our users enough confidence. It also removes the need to
>>>> do things just for the sake of the current policy rather than because
>>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>>
>>>> Just to make myself clear: I think we should definitely stick with
>>>> our
>>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>>
>>>> My +1 to all 4 points above.
>>>>
>>>> -Michael
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org<mailto:
>>>> java-dev-unsubscribe@lucene.apache.org>
>>>> For additional commands, e-mail: java-dev-help@lucene.apache.org<mailto:
>>>> java-dev-help@lucene.apache.org>
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>
>>
>>
>
> --
> - Mark
>
> http://www.lucidimagination.com
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
Re: Proposal for changing the backwards-compatibility policy
Posted by Mark Miller <ma...@gmail.com>.
I would guess you hit what I call "thread fatigue" by the time you
summed that up :)
Michael hasn't been around for a bit - perhaps it was easier for him to
spawn a new thread.
Also, much shorter text to read :)
Shai Erera wrote:
> Ahh ... I wish I had finished
> http://www.nabble.com/Re%3A-Lucene%27s-default-settings---back-compatibility-p23792927.html
> with +1 of my own. Guess that's what was missing to get it to closure :).
>
> Shai
>
> On Tue, Jun 16, 2009 at 7:03 PM, Michael Busch <buschmic@gmail.com
> <ma...@gmail.com>> wrote:
>
> I'd suggest to treat a runtime change like an API change (unless
> it's fixing a bug of course),
> i.e. giving a warning, providing a switch, switching the default
> behavior only after a major
> or minor release was around that had the warning/switch.
>
> Michael
>
>
>
> On 6/16/09 8:54 AM, Earwin Burrfoot wrote:
>> Oh yes! Again!
>> +1
>>
>> One point is missing. What about incompatible behavioral changes that
>> do not touch API and file format?
>> Like posIncr=0 at the first token in stream, or analyzer fixes, or
>> something along these lines.
>>
>> Are we free to introduce them in a minor release without warning, or
>> are we going to warn one release before the change, or do we provide
>> old-behaviour switches that are deprecated since their birth, or we
>> keep said switches for a couple of major releases?
>>
>>
>> On Tue, Jun 16, 2009 at 14:37, Michael Busch<bu...@gmail.com> <ma...@gmail.com> wrote:
>>
>>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>>> didn't fully read the incredibly long recent thread about
>>> backwards-compatibility, so maybe what I'm about to propose has been
>>> proposed already. In that case my apologies in advance.
>>>
>>> Rather than discussing our current backwards-compatibility policy
>>> again, I'd like to make here a concrete proposal for changing the policy
>>> after Lucene 3.0 is released.
>>>
>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>>> use different names; just for convenience here...)
>>>
>>> 1. The file format backwards-compatiblity policy will remain unchanged;
>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>> indexes.
>>>
>>> 2. Deprecated public and protected APIs can be removed if they have
>>> been released in at least one major or minor release. E.g. an 3.1
>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>> (if 4.0 comes after 3.2).
>>>
>>> 3. No public or protected APIs are changed in a bugfix release; except
>>> if a severe bug can't be changed otherwise.
>>>
>>> 4. Each release will have release notes with a new section
>>> "Incompatible changes", which lists, as the names says, all changes that
>>> break backwards compatibility. The list should also have information
>>> about how to convert to the new API. I think the eclipse releases
>>> have such a release notes section.
>>>
>>>
>>> The big change here apparently is 2. Consider the current situation:
>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>> remove it a month later in 3.0, while still complying with our current
>>> backwards-compatibility policy. A transition period of one month is
>>> very short for such an important API. On the other hand, a transition
>>> period of presumably >2 years, until 4.0 is released, seems very long
>>> to stick with a deprecated API that clutters the APIs and docs. With
>>> the proposed change, we couldn't do that. Given our current release
>>> schedule, the transition period would at least be 6-9 months, which
>>> seems a very reasonable timeframe.
>>>
>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>> deprecate after one major or minor release already. We could for a
>>> very popular API like the TokenStream API send a mail to java-user,
>>> asking if people need more transition time and be flexible.
>>>
>>> I think this policy is much more dynamic and flexible, but should
>>> still give our users enough confidence. It also removes the need to
>>> do things just for the sake of the current policy rather than because
>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>
>>> Just to make myself clear: I think we should definitely stick with our
>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>
>>> My +1 to all 4 points above.
>>>
>>> -Michael
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org <ma...@lucene.apache.org>
>>> For additional commands, e-mail: java-dev-help@lucene.apache.org <ma...@lucene.apache.org>
>>>
>>>
>>>
>>
>
>
--
- Mark
http://www.lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Shai Erera <se...@gmail.com>.
Ahh ... I wish I had finished
http://www.nabble.com/Re%3A-Lucene%27s-default-settings---back-compatibility-p23792927.htmlwith
+1 of my own. Guess that's what was missing to get it to closure :).
Shai
On Tue, Jun 16, 2009 at 7:03 PM, Michael Busch <bu...@gmail.com> wrote:
> I'd suggest to treat a runtime change like an API change (unless it's
> fixing a bug of course),
> i.e. giving a warning, providing a switch, switching the default behavior
> only after a major
> or minor release was around that had the warning/switch.
>
> Michael
>
>
>
> On 6/16/09 8:54 AM, Earwin Burrfoot wrote:
>
> Oh yes! Again!
> +1
>
> One point is missing. What about incompatible behavioral changes that
> do not touch API and file format?
> Like posIncr=0 at the first token in stream, or analyzer fixes, or
> something along these lines.
>
> Are we free to introduce them in a minor release without warning, or
> are we going to warn one release before the change, or do we provide
> old-behaviour switches that are deprecated since their birth, or we
> keep said switches for a couple of major releases?
>
>
> On Tue, Jun 16, 2009 at 14:37, Michael Busch<bu...@gmail.com> <bu...@gmail.com> wrote:
>
>
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
>
>
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
I'd suggest to treat a runtime change like an API change (unless it's
fixing a bug of course),
i.e. giving a warning, providing a switch, switching the default
behavior only after a major
or minor release was around that had the warning/switch.
Michael
On 6/16/09 8:54 AM, Earwin Burrfoot wrote:
> Oh yes! Again!
> +1
>
> One point is missing. What about incompatible behavioral changes that
> do not touch API and file format?
> Like posIncr=0 at the first token in stream, or analyzer fixes, or
> something along these lines.
>
> Are we free to introduce them in a minor release without warning, or
> are we going to warn one release before the change, or do we provide
> old-behaviour switches that are deprecated since their birth, or we
> keep said switches for a couple of major releases?
>
>
> On Tue, Jun 16, 2009 at 14:37, Michael Busch<bu...@gmail.com> wrote:
>
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>> indexes.
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>> if a severe bug can't be changed otherwise.
>>
>> 4. Each release will have release notes with a new section
>> "Incompatible changes", which lists, as the names says, all changes that
>> break backwards compatibility. The list should also have information
>> about how to convert to the new API. I think the eclipse releases
>> have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably>2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>
>>
>>
>
>
>
>
Re: Proposal for changing the backwards-compatibility policy
Posted by Earwin Burrfoot <ea...@gmail.com>.
Oh yes! Again!
+1
One point is missing. What about incompatible behavioral changes that
do not touch API and file format?
Like posIncr=0 at the first token in stream, or analyzer fixes, or
something along these lines.
Are we free to introduce them in a minor release without warning, or
are we going to warn one release before the change, or do we provide
old-behaviour switches that are deprecated since their birth, or we
keep said switches for a couple of major releases?
On Tue, Jun 16, 2009 at 14:37, Michael Busch<bu...@gmail.com> wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
--
Kirill Zakharenko/Кирилл Захаренко (earwin@gmail.com)
Home / Mobile: +7 (495) 683-567-4 / +7 (903) 5-888-423
ICQ: 104465785
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael McCandless <lu...@mikemccandless.com>.
On Tue, Jun 16, 2009 at 12:41 PM, DM Smith<dm...@gmail.com> wrote:
> I'll reiterate what this means to me. It is more than just file format
> stability. An index must still be useful. An index is invalidated if the
> analyzers, filters and/or token streams produce a different result. If these
> change, the index is not really readable.
I agree: what's the point of keeping index format compatibility for so
long if tokenizers can produce different tokens. It seems like index
file format & "the tokens produced by core tokenizers/filters" should
have the same policy. Worse, it's necessary to be able to produce
"old" tokens, compatibly, since you may have an "old" index. You
don't want a mix of old & new tokens in your index.
I think matchVersion is a great way to address these. We'd only add
it to those analyzers that needed to change across versions, on
demand.
Mike
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
On 6/16/09 9:41 AM, DM Smith wrote:
>
> Perhaps you should go back and see why the thread died.
OK I will read it.
I think we should do the following:
I'll send the mentioned mail to the user list and wait for feedback.
After a decent amount of time for feedback I will call a vote on
java-dev where committers and/or PMC members will vote for or against
the proposal. I'll include the links to the old thread, this thread and
the thread on java-user. The committers/PMC members will then make a
decision based on what they think is in the best interest of Lucene and
its users.
Given that we should probably not discuss the same issues again here
that were already in the old thread and can be found in the archives. Of
course feel free to bring up new concerns here that weren't covered in
the old thread yet.
Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by DM Smith <dm...@gmail.com>.
Mark Miller wrote:
> I'm inclined to agree to a large extent. If we want to remove
> deprecations more often, why not release major versions more often?
>
> The main ramification I see being that the index back compat period
> could be significantly shortened time wise with the current policy.
I don't think that there is a requirement that 5.x, or later, *must not*
be able to read 3.x. It is merely an allowance.
Conversely, the side effect of using minor releases as major ones is
that we indefinitely postpone the allowable breaking of index
compatibility. With this proposal, what would ever drive a 4.0 release?
-- DM
>
> DM Smith wrote:
>>
>> Michael Busch wrote:
>>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>>> didn't fully read the incredibly long recent thread about
>>> backwards-compatibility, so maybe what I'm about to propose has been
>>> proposed already. In that case my apologies in advance.
>> Perhaps you should go back and see why the thread died. The points I
>> made earlier, at the end of the thread, are still pertinent. I'll
>> highlight some of that again.
>>
>>>
>>> Rather than discussing our current backwards-compatibility policy
>>> again, I'd like to make here a concrete proposal for changing the
>>> policy
>>> after Lucene 3.0 is released.
>>>
>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>>> use different names; just for convenience here...)
>>>
>>> 1. The file format backwards-compatiblity policy will remain unchanged;
>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>> indexes.
>> I'll reiterate what this means to me. It is more than just file
>> format stability. An index must still be useful. An index is
>> invalidated if the analyzers, filters and/or token streams produce a
>> different result. If these change, the index is not really readable.
>>
>>>
>>> 2. Deprecated public and protected APIs can be removed if they have
>>> been released in at least one major or minor release. E.g. an 3.1
>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>> (if 4.0 comes after 3.2).
>>
>> To support #2, in view of #1, we need robust test cases that focus on
>> input and output of the invariants of analyzers, filters and token
>> streams. We may already have this.
>>
>> Regarding #1 and #2, I think that bug fixes should not be held back
>> when it changes these outputs.
>>
>> I'll reiterate here too. This will cause Linux distributions, such as
>> Debian, to number Lucene differently. This will cause confusion.
>>
>> The Debian policy is to bump the major revision number every time
>> there is an incompatible API change.
>>
>> This really is not necessary. We already have a sufficient mechanism
>> to do #2: just do a major release. But it requires frequent releases.
>>>
>>> 3. No public or protected APIs are changed in a bugfix release; except
>>> if a severe bug can't be changed otherwise.
>>
>> Just as important as the signatures, the input/output relationships
>> should not change, except to fix an undebatable bug.
>>>
>>> 4. Each release will have release notes with a new section
>>> "Incompatible changes", which lists, as the names says, all
>>> changes that
>>> break backwards compatibility. The list should also have information
>>> about how to convert to the new API. I think the eclipse releases
>>> have such a release notes section.
>>>
>>>
>>> The big change here apparently is 2. Consider the current situation:
>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>> remove it a month later in 3.0, while still complying with our current
>>> backwards-compatibility policy. A transition period of one month is
>>> very short for such an important API. On the other hand, a transition
>>> period of presumably >2 years, until 4.0 is released, seems very long
>>> to stick with a deprecated API that clutters the APIs and docs. With
>>> the proposed change, we couldn't do that. Given our current release
>>> schedule, the transition period would at least be 6-9 months, which
>>> seems a very reasonable timeframe.
>>>
>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>> deprecate after one major or minor release already. We could for a
>>> very popular API like the TokenStream API send a mail to java-user,
>>> asking if people need more transition time and be flexible.
>>>
>>> I think this policy is much more dynamic and flexible, but should
>>> still give our users enough confidence. It also removes the need to
>>> do things just for the sake of the current policy rather than because
>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>
>>> Just to make myself clear: I think we should definitely stick with our
>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>
>>> My +1 to all 4 points above.
>>>
>>> -Michael
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Mark Miller <ma...@gmail.com>.
I'm inclined to agree to a large extent. If we want to remove
deprecations more often, why not release major versions more often?
The main ramification I see being that the index back compat period
could be significantly shortened time wise with the current policy.
DM Smith wrote:
>
> Michael Busch wrote:
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
> Perhaps you should go back and see why the thread died. The points I
> made earlier, at the end of the thread, are still pertinent. I'll
> highlight some of that again.
>
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>> indexes.
> I'll reiterate what this means to me. It is more than just file format
> stability. An index must still be useful. An index is invalidated if
> the analyzers, filters and/or token streams produce a different
> result. If these change, the index is not really readable.
>
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>
> To support #2, in view of #1, we need robust test cases that focus on
> input and output of the invariants of analyzers, filters and token
> streams. We may already have this.
>
> Regarding #1 and #2, I think that bug fixes should not be held back
> when it changes these outputs.
>
> I'll reiterate here too. This will cause Linux distributions, such as
> Debian, to number Lucene differently. This will cause confusion.
>
> The Debian policy is to bump the major revision number every time
> there is an incompatible API change.
>
> This really is not necessary. We already have a sufficient mechanism
> to do #2: just do a major release. But it requires frequent releases.
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>> if a severe bug can't be changed otherwise.
>
> Just as important as the signatures, the input/output relationships
> should not change, except to fix an undebatable bug.
>>
>> 4. Each release will have release notes with a new section
>> "Incompatible changes", which lists, as the names says, all
>> changes that
>> break backwards compatibility. The list should also have information
>> about how to convert to the new API. I think the eclipse releases
>> have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably >2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> 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
>
--
- Mark
http://www.lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by DM Smith <dm...@gmail.com>.
Michael McCandless wrote:
> On Tue, Jun 16, 2009 at 12:41 PM, DM Smith<dm...@gmail.com> wrote:
>
>
>> The Debian policy is to bump the major revision number every time there is an incompatible API change.
>>
>
> Does this include adding methods to interfaces? Ie, is there some
> automated check done by Debian that roughly matches our "JAR
> drop-in-ability"?
The Debian process is manual, driven by policy.
IIRC, they look at the CHANGES.txt to see if, according to their policy,
it is a new major version, a new minor version or just a bug fix and
base their decision on that.
BTW, JPackage considers every release of Lucene to break backward
compatibility since they look at Lucene, core and contrib, as a whole.
They retain the Lucene numbering.
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael McCandless <lu...@mikemccandless.com>.
On Tue, Jun 16, 2009 at 12:41 PM, DM Smith<dm...@gmail.com> wrote:
> The Debian policy is to bump the major revision number every time there is an incompatible API change.
Does this include adding methods to interfaces? Ie, is there some
automated check done by Debian that roughly matches our "JAR
drop-in-ability"?
Mike
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by DM Smith <dm...@gmail.com>.
Michael Busch wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
Perhaps you should go back and see why the thread died. The points I
made earlier, at the end of the thread, are still pertinent. I'll
highlight some of that again.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
I'll reiterate what this means to me. It is more than just file format
stability. An index must still be useful. An index is invalidated if the
analyzers, filters and/or token streams produce a different result. If
these change, the index is not really readable.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
To support #2, in view of #1, we need robust test cases that focus on
input and output of the invariants of analyzers, filters and token
streams. We may already have this.
Regarding #1 and #2, I think that bug fixes should not be held back when
it changes these outputs.
I'll reiterate here too. This will cause Linux distributions, such as
Debian, to number Lucene differently. This will cause confusion.
The Debian policy is to bump the major revision number every time there
is an incompatible API change.
This really is not necessary. We already have a sufficient mechanism to
do #2: just do a major release. But it requires frequent releases.
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
Just as important as the signatures, the input/output relationships
should not change, except to fix an undebatable bug.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes
> that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> 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: Proposal for changing the backwards-compatibility policy
Posted by Shai Erera <se...@gmail.com>.
Index back-compat is guaranteed to hold within minor releases.
On Tue, Jun 16, 2009 at 6:59 PM, Yonik Seeley <yo...@lucidimagination.com>wrote:
> So under this proposal, what's the difference between a major and minor
> release?
>
> -Yonik
> http://www.lucidimagination.com
>
>
>
> On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
> > Probably everyone is thinking right now "Oh no! Not again!". I admit I
> > didn't fully read the incredibly long recent thread about
> > backwards-compatibility, so maybe what I'm about to propose has been
> > proposed already. In that case my apologies in advance.
> >
> > Rather than discussing our current backwards-compatibility policy
> > again, I'd like to make here a concrete proposal for changing the policy
> > after Lucene 3.0 is released.
> >
> > I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> > 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> > use different names; just for convenience here...)
> >
> > 1. The file format backwards-compatiblity policy will remain unchanged;
> > i.e. Lucene X.Y supports reading all indexes written with Lucene
> > X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> > indexes.
> >
> > 2. Deprecated public and protected APIs can be removed if they have
> > been released in at least one major or minor release. E.g. an 3.1
> > API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> > (if 4.0 comes after 3.2).
> >
> > 3. No public or protected APIs are changed in a bugfix release; except
> > if a severe bug can't be changed otherwise.
> >
> > 4. Each release will have release notes with a new section
> > "Incompatible changes", which lists, as the names says, all changes
> that
> > break backwards compatibility. The list should also have information
> > about how to convert to the new API. I think the eclipse releases
> > have such a release notes section.
> >
> >
> > The big change here apparently is 2. Consider the current situation:
> > We can release e.g. the new TokenStream API with 2.9; then we can
> > remove it a month later in 3.0, while still complying with our current
> > backwards-compatibility policy. A transition period of one month is
> > very short for such an important API. On the other hand, a transition
> > period of presumably >2 years, until 4.0 is released, seems very long
> > to stick with a deprecated API that clutters the APIs and docs. With
> > the proposed change, we couldn't do that. Given our current release
> > schedule, the transition period would at least be 6-9 months, which
> > seems a very reasonable timeframe.
> >
> > We should also not consider 2. as a must. I.e. we don't *have* to
> > deprecate after one major or minor release already. We could for a
> > very popular API like the TokenStream API send a mail to java-user,
> > asking if people need more transition time and be flexible.
> >
> > I think this policy is much more dynamic and flexible, but should
> > still give our users enough confidence. It also removes the need to
> > do things just for the sake of the current policy rather than because
> > they make the most sense, like our somewhat goofy X.9 releases. :)
> >
> > Just to make myself clear: I think we should definitely stick with our
> > 2.9 and 3.0 plans and change the policy afterwards.
> >
> > My +1 to all 4 points above.
> >
> > -Michael
> >
> >
> > ---------------------------------------------------------------------
> > 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: Proposal for changing the backwards-compatibility policy
Posted by Mark Miller <ma...@gmail.com>.
Yeah, the only difference now is that we can remove deprecated APIs. And
I guess we add nothing.
Which is, as Micahel has said, is goofy.
3.0 will be 2.9 like 1.9 was 2.0. Without deprecations.
Not a big deal at all, but I find it goofy too.
- Mark
Michael Busch wrote:
> From a backwards-compatibility point of view, nothing really.
>
> Michael
>
> On 6/16/09 8:59 AM, Yonik Seeley wrote:
>> So under this proposal, what's the difference between a major and minor release?
>>
>> -Yonik
>> http://www.lucidimagination.com
>>
>>
>>
>> On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
>>
>>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>>> didn't fully read the incredibly long recent thread about
>>> backwards-compatibility, so maybe what I'm about to propose has been
>>> proposed already. In that case my apologies in advance.
>>>
>>> Rather than discussing our current backwards-compatibility policy
>>> again, I'd like to make here a concrete proposal for changing the policy
>>> after Lucene 3.0 is released.
>>>
>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>>> use different names; just for convenience here...)
>>>
>>> 1. The file format backwards-compatiblity policy will remain unchanged;
>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>> indexes.
>>>
>>> 2. Deprecated public and protected APIs can be removed if they have
>>> been released in at least one major or minor release. E.g. an 3.1
>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>> (if 4.0 comes after 3.2).
>>>
>>> 3. No public or protected APIs are changed in a bugfix release; except
>>> if a severe bug can't be changed otherwise.
>>>
>>> 4. Each release will have release notes with a new section
>>> "Incompatible changes", which lists, as the names says, all changes that
>>> break backwards compatibility. The list should also have information
>>> about how to convert to the new API. I think the eclipse releases
>>> have such a release notes section.
>>>
>>>
>>> The big change here apparently is 2. Consider the current situation:
>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>> remove it a month later in 3.0, while still complying with our current
>>> backwards-compatibility policy. A transition period of one month is
>>> very short for such an important API. On the other hand, a transition
>>> period of presumably >2 years, until 4.0 is released, seems very long
>>> to stick with a deprecated API that clutters the APIs and docs. With
>>> the proposed change, we couldn't do that. Given our current release
>>> schedule, the transition period would at least be 6-9 months, which
>>> seems a very reasonable timeframe.
>>>
>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>> deprecate after one major or minor release already. We could for a
>>> very popular API like the TokenStream API send a mail to java-user,
>>> asking if people need more transition time and be flexible.
>>>
>>> I think this policy is much more dynamic and flexible, but should
>>> still give our users enough confidence. It also removes the need to
>>> do things just for the sake of the current policy rather than because
>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>
>>> Just to make myself clear: I think we should definitely stick with our
>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>
>>> My +1 to all 4 points above.
>>>
>>> -Michael
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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
>>
>>
>>
>
--
- Mark
http://www.lucidimagination.com
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org
Re: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
Except regarding file format compatibility, see 1.
On 6/16/09 9:04 AM, Michael Busch wrote:
> >From a backwards-compatibility point of view, nothing really.
>
> Michael
>
> On 6/16/09 8:59 AM, Yonik Seeley wrote:
>> So under this proposal, what's the difference between a major and minor release?
>>
>> -Yonik
>> http://www.lucidimagination.com
>>
>>
>>
>> On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
>>
>>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>>> didn't fully read the incredibly long recent thread about
>>> backwards-compatibility, so maybe what I'm about to propose has been
>>> proposed already. In that case my apologies in advance.
>>>
>>> Rather than discussing our current backwards-compatibility policy
>>> again, I'd like to make here a concrete proposal for changing the policy
>>> after Lucene 3.0 is released.
>>>
>>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>>> use different names; just for convenience here...)
>>>
>>> 1. The file format backwards-compatiblity policy will remain unchanged;
>>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>>> indexes.
>>>
>>> 2. Deprecated public and protected APIs can be removed if they have
>>> been released in at least one major or minor release. E.g. an 3.1
>>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>>> (if 4.0 comes after 3.2).
>>>
>>> 3. No public or protected APIs are changed in a bugfix release; except
>>> if a severe bug can't be changed otherwise.
>>>
>>> 4. Each release will have release notes with a new section
>>> "Incompatible changes", which lists, as the names says, all changes that
>>> break backwards compatibility. The list should also have information
>>> about how to convert to the new API. I think the eclipse releases
>>> have such a release notes section.
>>>
>>>
>>> The big change here apparently is 2. Consider the current situation:
>>> We can release e.g. the new TokenStream API with 2.9; then we can
>>> remove it a month later in 3.0, while still complying with our current
>>> backwards-compatibility policy. A transition period of one month is
>>> very short for such an important API. On the other hand, a transition
>>> period of presumably>2 years, until 4.0 is released, seems very long
>>> to stick with a deprecated API that clutters the APIs and docs. With
>>> the proposed change, we couldn't do that. Given our current release
>>> schedule, the transition period would at least be 6-9 months, which
>>> seems a very reasonable timeframe.
>>>
>>> We should also not consider 2. as a must. I.e. we don't *have* to
>>> deprecate after one major or minor release already. We could for a
>>> very popular API like the TokenStream API send a mail to java-user,
>>> asking if people need more transition time and be flexible.
>>>
>>> I think this policy is much more dynamic and flexible, but should
>>> still give our users enough confidence. It also removes the need to
>>> do things just for the sake of the current policy rather than because
>>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>>
>>> Just to make myself clear: I think we should definitely stick with our
>>> 2.9 and 3.0 plans and change the policy afterwards.
>>>
>>> My +1 to all 4 points above.
>>>
>>> -Michael
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
From a backwards-compatibility point of view, nothing really.
Michael
On 6/16/09 8:59 AM, Yonik Seeley wrote:
> So under this proposal, what's the difference between a major and minor release?
>
> -Yonik
> http://www.lucidimagination.com
>
>
>
> On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
>
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>> indexes.
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>> if a severe bug can't be changed otherwise.
>>
>> 4. Each release will have release notes with a new section
>> "Incompatible changes", which lists, as the names says, all changes that
>> break backwards compatibility. The list should also have information
>> about how to convert to the new API. I think the eclipse releases
>> have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably>2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> 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: Proposal for changing the backwards-compatibility policy
Posted by Yonik Seeley <yo...@lucidimagination.com>.
So under this proposal, what's the difference between a major and minor release?
-Yonik
http://www.lucidimagination.com
On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> 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: Proposal for changing the backwards-compatibility policy
Posted by Michael Busch <bu...@gmail.com>.
Wow this is *very* similar! :)
On 6/16/09 4:29 AM, Shai Erera wrote:
> Since I proposed the same changes
> (http://www.nabble.com/Re%3A-Lucene%27s-default-settings---back-compatibility-p23792927.html),
> I can only give my +1 to all 4 :).
>
> On the other thread I also proposed to change the policy around
> changing default settings. But maybe we should take it one step at a time.
>
> Shai
>
> On Tue, Jun 16, 2009 at 1:37 PM, Michael Busch <buschmic@gmail.com
> <ma...@gmail.com>> wrote:
>
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the
> policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain
> unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all
> changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> <ma...@lucene.apache.org>
> For additional commands, e-mail: java-dev-help@lucene.apache.org
> <ma...@lucene.apache.org>
>
>
Re: Proposal for changing the backwards-compatibility policy
Posted by Shai Erera <se...@gmail.com>.
Since I proposed the same changes (
http://www.nabble.com/Re%3A-Lucene%27s-default-settings---back-compatibility-p23792927.html),
I can only give my +1 to all 4 :).
On the other thread I also proposed to change the policy around changing
default settings. But maybe we should take it one step at a time.
Shai
On Tue, Jun 16, 2009 at 1:37 PM, Michael Busch <bu...@gmail.com> wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>
Re: Proposal for changing the backwards-compatibility policy
Posted by Simon Willnauer <si...@googlemail.com>.
+1 to all 4.
On Tue, Jun 16, 2009 at 2:07 PM, Michael
McCandless<lu...@mikemccandless.com> wrote:
> +1 to all 4.
>
> Mike
>
> On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
>> Probably everyone is thinking right now "Oh no! Not again!". I admit I
>> didn't fully read the incredibly long recent thread about
>> backwards-compatibility, so maybe what I'm about to propose has been
>> proposed already. In that case my apologies in advance.
>>
>> Rather than discussing our current backwards-compatibility policy
>> again, I'd like to make here a concrete proposal for changing the policy
>> after Lucene 3.0 is released.
>>
>> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
>> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
>> use different names; just for convenience here...)
>>
>> 1. The file format backwards-compatiblity policy will remain unchanged;
>> i.e. Lucene X.Y supports reading all indexes written with Lucene
>> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
>> indexes.
>>
>> 2. Deprecated public and protected APIs can be removed if they have
>> been released in at least one major or minor release. E.g. an 3.1
>> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
>> (if 4.0 comes after 3.2).
>>
>> 3. No public or protected APIs are changed in a bugfix release; except
>> if a severe bug can't be changed otherwise.
>>
>> 4. Each release will have release notes with a new section
>> "Incompatible changes", which lists, as the names says, all changes that
>> break backwards compatibility. The list should also have information
>> about how to convert to the new API. I think the eclipse releases
>> have such a release notes section.
>>
>>
>> The big change here apparently is 2. Consider the current situation:
>> We can release e.g. the new TokenStream API with 2.9; then we can
>> remove it a month later in 3.0, while still complying with our current
>> backwards-compatibility policy. A transition period of one month is
>> very short for such an important API. On the other hand, a transition
>> period of presumably >2 years, until 4.0 is released, seems very long
>> to stick with a deprecated API that clutters the APIs and docs. With
>> the proposed change, we couldn't do that. Given our current release
>> schedule, the transition period would at least be 6-9 months, which
>> seems a very reasonable timeframe.
>>
>> We should also not consider 2. as a must. I.e. we don't *have* to
>> deprecate after one major or minor release already. We could for a
>> very popular API like the TokenStream API send a mail to java-user,
>> asking if people need more transition time and be flexible.
>>
>> I think this policy is much more dynamic and flexible, but should
>> still give our users enough confidence. It also removes the need to
>> do things just for the sake of the current policy rather than because
>> they make the most sense, like our somewhat goofy X.9 releases. :)
>>
>> Just to make myself clear: I think we should definitely stick with our
>> 2.9 and 3.0 plans and change the policy afterwards.
>>
>> My +1 to all 4 points above.
>>
>> -Michael
>>
>>
>> ---------------------------------------------------------------------
>> 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: Proposal for changing the backwards-compatibility policy
Posted by Michael McCandless <lu...@mikemccandless.com>.
+1 to all 4.
Mike
On Tue, Jun 16, 2009 at 6:37 AM, Michael Busch<bu...@gmail.com> wrote:
> Probably everyone is thinking right now "Oh no! Not again!". I admit I
> didn't fully read the incredibly long recent thread about
> backwards-compatibility, so maybe what I'm about to propose has been
> proposed already. In that case my apologies in advance.
>
> Rather than discussing our current backwards-compatibility policy
> again, I'd like to make here a concrete proposal for changing the policy
> after Lucene 3.0 is released.
>
> I'll call X.Y -> X+1.0 a 'major release', X.Y -> X.Y+1 a
> 'minor release' and X.Y.Z -> X.Y.Z+1 a 'bugfix release'. (we can later
> use different names; just for convenience here...)
>
> 1. The file format backwards-compatiblity policy will remain unchanged;
> i.e. Lucene X.Y supports reading all indexes written with Lucene
> X-1.Y. That means Lucene 4.0 will not have to be able to read 2.x
> indexes.
>
> 2. Deprecated public and protected APIs can be removed if they have
> been released in at least one major or minor release. E.g. an 3.1
> API can be released as deprecated in 3.2 and removed in 3.3 or 4.0
> (if 4.0 comes after 3.2).
>
> 3. No public or protected APIs are changed in a bugfix release; except
> if a severe bug can't be changed otherwise.
>
> 4. Each release will have release notes with a new section
> "Incompatible changes", which lists, as the names says, all changes that
> break backwards compatibility. The list should also have information
> about how to convert to the new API. I think the eclipse releases
> have such a release notes section.
>
>
> The big change here apparently is 2. Consider the current situation:
> We can release e.g. the new TokenStream API with 2.9; then we can
> remove it a month later in 3.0, while still complying with our current
> backwards-compatibility policy. A transition period of one month is
> very short for such an important API. On the other hand, a transition
> period of presumably >2 years, until 4.0 is released, seems very long
> to stick with a deprecated API that clutters the APIs and docs. With
> the proposed change, we couldn't do that. Given our current release
> schedule, the transition period would at least be 6-9 months, which
> seems a very reasonable timeframe.
>
> We should also not consider 2. as a must. I.e. we don't *have* to
> deprecate after one major or minor release already. We could for a
> very popular API like the TokenStream API send a mail to java-user,
> asking if people need more transition time and be flexible.
>
> I think this policy is much more dynamic and flexible, but should
> still give our users enough confidence. It also removes the need to
> do things just for the sake of the current policy rather than because
> they make the most sense, like our somewhat goofy X.9 releases. :)
>
> Just to make myself clear: I think we should definitely stick with our
> 2.9 and 3.0 plans and change the policy afterwards.
>
> My +1 to all 4 points above.
>
> -Michael
>
>
> ---------------------------------------------------------------------
> 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